开源终端AI编程工具 opencode 实操指南：模型配置、Skills、Playwright 详解

1. 先说结论：opencode是什么，为什么值得关注

如果你最近在刷技术圈，大概率会被一个叫 opencode 的命令行工具刷屏。它是近半年社区活跃度增长最快的一类AI编程Agent之一，定位和 Claude Code、Codex CLI 类似，但走的是完全不同的路线：开源、终端优先、模块化设计，并且非常强调“本地可控”。

我花了一周时间把这个工具从安装到生产环境完整跑了一遍，包括命令行、VS Code插件、JetBrains插件、桌面客户端，以及它宣传的 Skills、LSP、Playwright 等高级能力。这篇文章会把我踩过的坑和觉得真正有用的地方全部整理出来，不是官方文档的翻译，是从一个普通开发者视角记录的完整实操笔记。

opencode 由 SST 团队发起并开源维护，目前支持 macOS、Linux、Windows 三大平台，底层可以接入 Claude、GPT、Gemini 以及各类兼容 OpenAI 协议的服务。它的核心卖点不是“又一个终端AI”，而是把 AI 编码助手做成了“可编程终端”：你可以给 AI 定义技能（Skills）、挂载语言服务器（LSP）、让它直接跑浏览器测试（Playwright）、还可以把多步操作写成固定流程。这些能力单独拆开都不算新鲜，但组合在一个开源终端工具里，目前做得比较完整的确实不多。

哪些人适合用 opencode？我个人认为：如果你正在用 Claude Code 或 Codex CLI，但对闭源工具的黑盒行为不满意；或者你需要在 IDE 之外、在 CI 环境里跑 AI 辅助代码审查；再或者你希望有一套能自己改源码的 AI 编码工具——那 opencode 值得认真看看。如果你是纯 IDE 用户，不碰终端，那也能用，因为它的 VSCode 和 JetBrains 插件做得还挺顺手，不过体验核心还是在终端里。

下面从安装开始，一步步来。

2. 安装：三种常见方式与一个必踩的坑

2.1 三种安装方式，按场景选

opencode 的官方安装方式有三种，分别对应不同使用习惯：

1. npm 全局安装（适合 Node.js 生态开发者）：

npm install -g opencode-ai

注意包名不是opencode，而是opencode-ai。这一点很容易踩坑，因为项目本身的命令名是opencode，但 npm 上的包名为了避让老项目，加了一个-ai后缀。我第一次直接npm i -g opencode，装到了一个完全不相关的旧包，浪费了十分钟。

2. Homebrew 安装（macOS 用户最省事）：

brew install sst/tap/opencode

这个 tap 源是官方维护的，升级也方便，brew upgrade就能更新到新版。

3. 安装脚本和二进制包（Linux/CI 环境更友好）：

curl -fsSL https://opencode.ai/install | bash

这条命令会下载对应平台的二进制，放到~/.opencode/bin。在 Linux 服务器或者 Docker 镜像里，我建议直接用这个方式，不依赖 Node 环境，体积也更小。

2.2 Windows 上的大坑：“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”

这个报错在 Windows 用户里出现频率极高，网上一搜一大片。根本原因其实很朴素：安装脚本把二进制放到了某个目录，但该目录没有加进 Windows 系统的 PATH 环境变量。

用 npm 安装后，正常情况下会把全局 bin 目录（通常是%APPDATA%\npm）加到 PATH。但如果你用的是 nvm-windows 或者其他 Node 版本管理器，npm 的全局目录可能不在默认 PATH 里。用 curl 脚本安装的话，脚本会把 opencode 放进~\.opencode\bin，但这个路径不会自动进入 PATH，需要手动加。

处理方式很简单：

1. 先确认装到了哪里，在 PowerShell 里执行：

Get-Command opencode -ErrorAction SilentlyContinue npm root -g

2. 找到实际的可执行文件路径，然后打开“系统属性 -> 环境变量”，把对应的 bin 目录加入用户 PATH。

3. 重新打开终端，执行opencode --version验证。

如果还是不行，还有一个更省事的土办法：直接用 npx 跑，不需要全局安装：

npx opencode-ai

这种方式把工具当临时依赖拉起来，适合只想尝鲜、不打算长期使用的场景。缺点也很明显：每次都要重新解析依赖，启动会慢一点，而且如果你在项目目录里用的是 pnpm 这类严格依赖管理工具，npx 的行为可能会被拦截。

2.3 升级与版本验证

opencode 的迭代速度非常快，基本一周一个版本。我建议养成定期升级的习惯，因为新功能往往伴随着模型 SDK 的更新，老版本容易出现“模型返回格式不兼容”之类的问题。

# npm 方式 npm update -g opencode-ai # brew 方式 brew upgrade opencode # 二进制方式，重跑安装脚本即可 curl -fsSL https://opencode.ai/install | bash

升级后用opencode --version查看版本号。如果你想体验最新的大版本，比如 2.0 之后的改动，也可以关注官方的 changelog再决定是否升级，毕竟正式环境里稳定性优先。

3. 模型接入与订阅选择：把“模型不可用”问题一次说清

3.1 opencode 支持哪些模型，以及“opencode go”是什么

opencode 本身不生产模型，它是模型的中立调度层。目前常用的接入方式有两种：一是使用官方托管的订阅服务（社区里常说的 opencode go 或者 opencode 套餐），二是在 opencode.json 里自己配置 API Key，指向 Anthropic、OpenAI、Google 等官方接口，或者任何兼容接口。

如果你走订阅路线，opencode 官方会提供一个统一的 API 网关，你在本地配置一个 API Key，然后在模型列表里选择即可。这种方式的优点是：不用自己维护多个模型的 API Key，计费也集中在一起；缺点是：部分区域的网络访问可能连不上网关，或者某些模型有地域限制，这时候就会出现一个让人血压升高的报错：

This model is not available in your country.

这个报错其实不一定是 opencode 的锅。官方网关背后的上游模型服务方（比如 Anthropic、OpenAI、Google）对部分模型有地域开放策略，如果你的出口 IP 落在限制区域内，上游会直接拒绝服务。opencode 只是把上游返回的错误透传出来。

针对这个问题，我能给的建议是：

• 检查你当前使用的模型是否在官方支持列表内，有些区域限制是模型级别的，换一个同厂商但不受限的模型可能就行；
• 如果你配置的是三方 API 中转，那么中转服务本身的地域策略才是关键，需要跟服务方确认；
• 如果只是偶尔测试，可以换用本地模型或者免费模型，避开地域限制。

这里特别提醒一句：网上有很多教程会建议你通过修改 IP 归属地的方式强行访问，这种方式我不推荐，一是不稳定，二是可能违反模型服务的用户协议，拿官方 Key 乱试还有被封号的风险。正经开发场景下，要么选官方可用区域的模型，要么在国内用合规的大模型服务商提供的 OpenAI 兼容接口。

3.2 免费模型与本地模型怎么配

opencode 支持通过 Ollama 接入本地开源模型，比如 Qwen、Llama 系列。配置方式是在 opencode.json 里声明本地模型服务地址：

{ "provider": { "ollama": { "npm": "@ai-sdk/ollama", "options": { "baseURL": "http://localhost:11434/api" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen 2.5 Coder 14B" } } } } }

本地模型的优势是隐私好、无地域限制、不花钱；缺点是中等配置的电脑跑 14B 模型已经很吃力，代码生成的连贯性和复杂任务的理解能力跟云端大模型还是有差距。我一般把本地模型用在两类场景：一是代码片段翻译、格式化、简单重构，二是网络隔离环境里做静态代码分析。真正接手项目级别的需求，还是得用云端模型。

3.3 社区热词“ccswitch 配置 opencode”到底是什么意思

经常有人在搜“opencode 接入 ccswitch”“ccswitch 配置 opencode”这类关键词。先说清楚：ccswitch 是一个 API 请求转换工具，它可以把不同服务商的接口格式转换成目标模型接口格式，同时支持到不同 API 网关之间的切换。

在 opencode 场景里，它的典型用途是这样的：你有一个服务商 A 的订阅，但 opencode 原生直连服务商 A 的效果不好，或者 opencode 不直接支持服务商 A 的接口格式；于是你起一个 ccswitch 本地服务，让 opencode 把请求发到http://localhost:某个端口，再由 ccswitch 转发到服务商 A 并做格式转换。这样 opencode 里配置的基地址就指向本地服务，实现了“模型路由的灵活切换”。

配置起来其实很简单。先启动 ccswitch，拿到本地端口号，然后在 opencode 的 provider 配置里把 baseURL 指过去：

{ "$schema": "https://opencode.ai/config.json", "provider": { "custom": { "npm": "@ai-sdk/openai-compatible", "name": "Custom Gateway", "options": { "baseURL": "http://localhost:8080/v1" }, "models": { "my-model": { "name": "My Model" } } } } }

ccswitch 这类工具本身不违法也不违规，就是开发者为了统一管理 API 接入而做的工具。但要注意，如果你配的是某服务商不支持的区域或模型，ccswitch 并不能帮你合法地绕过限制。它的价值在于“格式转换”和“多服务商统一管理”，而不是“网络穿透”。搞清楚这个边界，才不会把技术问题搞成合规问题。

3.4 模型选择建议：日常开发我这么配

我自己在终端里同时挂了三个模型：

• 日常对话和代码生成：Claude 系列，理解长上下文能力强，改代码时少犯低级错误；
• 代码补全和快速问答：GPT 系列，响应快，API 稳定；
• 简单替换/格式化：本地 Qwen 或者免费模型，省配额。

通过 opencode 的模型选择快捷键，可以在一次会话里随时切换模型，这个体验比 Claude Code 默认只能绑定单一模型要舒服得多。具体如何切换，下面的实操部分会说。

4. 配置与项目实战：从 opencode.json 到正式接手项目

4.1 全局配置与项目配置的拆分

opencode 的配置遵循“全局 + 项目”双层结构。全局配置文件在用户主目录下，存放通用的模型偏好、主题风格和认证信息；项目配置则放在.opencode/目录下，跟仓库一起提交，方便团队统一 AI 辅助行为。

全局配置文件位置：

• Linux / macOS：~/.config/opencode/opencode.json
• Windows：%USERPROFILE%\.config\opencode\opencode.json

项目配置文件位置：

• 项目根目录下的opencode.json
• 或者.opencode/opencode.json

我习惯把模型凭据放在全局配置，把项目的语言栈、自定义技能、忽略规则放在项目配置。这样团队协作时，每个人只需要配好自己的 API Key 就能跑起来。

4.2 Linux 环境修改 JSON 的几个注意点

有热词提到“opencode linux 修改 json”，我猜是在 Linux 服务器上配置时遇到权限或者语法问题。这里分享几个实实在在的注意点：

1. JSON 文件不能带注释。opencode 的配置文件是标准 JSON，不是 JSONC，//注释会直接导致解析报错。网上有些教程会让你加注释，那是老版本的行为，新版已经移除了。

2. 路径问题。在 Linux 上用安装脚本装的话，配置文件读取顺序有一个隐含优先级：项目配置会覆盖全局配置的同名字段。如果你改了全局配置发现没生效，先检查项目里有没有同名配置把它盖掉了。

3. 权限问题。如果配置文件包含密钥，建议chmod 600。opencode 在读取时不强制检查权限，但安全意识还是要有的，毕竟 API Key 泄露的后果是你自己的钱包承担。

4. 修改配置后不用重启服务，opencode 会在下次启动时重新加载；但如果是在会话中修改，可能需要退出重进。

4.3 快速上手：让 opencode 接手一个老项目

这里我记录一次真实的项目实施过程。我拉了一个半年前写的后端项目，技术栈是 Java 21 + Spring Boot + Maven，代码有点乱，官方文档缺失，我让 opencode 先梳理项目结构。

进入项目目录，运行：

opencode

它会启动一个 TUI 交互界面，底部是输入框，顶部是会话记录，左侧可以查看文件树。第一次进入会要求登录并选择模型。

我输入的第一条指令是：“请分析这个项目的 Maven 依赖，梳理模块结构，并找出启动入口。”

这一条指令其实默认会触发几个动作：opencode 读取当前工作目录的文件树、提取关键文件内容（pom.xml、主类、配置文件）、再根据代码逻辑推断分层。它返回结构比我预期好，直接给出了模块划分、依赖关系图和启动命令。我还发现它自动用了 MCP 工具读取了文件，这说明它对 Maven 项目的认知不是简单读文件，而是有一定构建工具层面的理解。

接着我让它“给 UserService 加一个分页查询方法，并补上单元测试”。它先定位了 UserService、UserMapper、数据库表结构，再生成代码，最后自己跑了 Maven 测试用例。整个过程除了有些 import 需要手动整理，基本没有需要返工的地方。

在我实际操作中，opencode 接手老项目时最强的一点是：它不像一些 AI 工具那样“张嘴就来”，而是先读取文件、确认上下文，再动手。这种先探索后执行的机制，让它在大型代码库里生成的代码贴合度明显高很多。

4.4 mvn 配置与 Java 生态的适配

Java 项目的 AI 辅助有两个痛点：一是依赖理解，二是测试运行。opencode 对 Maven 的支持体现在两个层面：

• 它读取pom.xml来理解项目的依赖树，从而在生成代码时知道哪些类库可用，避免生成import一个根本不存在的库；
• 它可以通过配置执行 Maven 命令，比如跑测试、编译、打包，并把结果反馈到会话里修正代码。

如果项目里有mvnw（Maven Wrapper），opencode 默认会优先使用./mvnw而不是系统安装的mvn。这个细节很关键，因为不同 JDK 版本下系统 mvn 的行为可能不一致，而 Wrapper 锁定了版本，行为更可控。

我建议在项目里加上.opencode/ignore文件，把target/、node_modules/这类目录排除，避免 AI 读入大量无用二进制和依赖文件，能显著降低上下文占用，回答也会更聚焦。

5. 深入一点点：Skills、LSP、Memory 这几个关键词到底怎么用

5.1 Skills：把常用操作封装成“技能”

Skills 是 opencode 早期就有的特色功能，但很多人在 2.0 之前都没用过。它本质上是一种“预定义指令模板”，把一段常见操作的完整指令固化下来，你输入一个斜杠命令就能触发。

举例：我经常要给前端代码加 API 类型定义，我把这个操作封装成一个 skill：

opencode skill add api-types

然后它会打开编辑器，让你编写这个技能的 prompt 模板和描述。模板里可以引用变量、读取当前文件，也可以联动执行 shell 命令。

实际效果是，你在会话里输入/api-types，opencode 就会自动执行“读取当前目录类型文件 -> 分析后端接口 -> 生成前端 TypeScript 类型 -> 写入对应 d.ts 文件”这个完整流程。

Skills 非常适合团队标准化。比如“代码审查 skill”“提交信息生成 skill”“数据库迁移 skill”，每个成员都能用同样的方式触发同样的质检标准。跟大模型的 Prompt 模板不同，Skills 是与代码操作绑定的，它不只是“告诉模型怎么做”，还可以让模型真的动手做。

5.2 LSP：怎么给 opencode 挂上语言服务器

LSP（Language Server Protocol）是 opencode 一个被低估的能力。以前我们聊 LSP，基本只关心它在 IDE 里的代码补全、跳转、诊断作用。而 opencode 把 LSP 用在了另一个地方：让 AI 具备对代码库的“结构化感知”。

它通过 LSP 获取符号定义、引用关系、诊断信息，而不是单纯靠模型自己去猜代码结构。这种能力在“理解大型代码库”的任务里尤其有用，比如你让 AI 找出某个接口的所有实现类，或者统计某个方法的全部调用链。

配置方法：在项目配置里声明需要启用的 LSP 服务端。

{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] }, "java": { "command": "jdtls", "args": ["-configuration", "/path/to/jdtls/config"] } } }

启用后，opencode 会启动对应的 LSP server，并在需要时向它发起语义查询。注意，每个语言服务器都会占用一部分内存和 CPU，项目多的时候建议按需启用；如果在 Docker 里跑，还要处理 LSP server 的生命周期。

结合我自己的体验：启用 TypeScript LSP 后，opencode 在重构前端代码时，引用的自动更新正确率高了不少；而在没有 LSP 时，它偶尔会漏改同名文件里的变量。

5.3 Memory：让 AI 记住项目的来龙去脉

社区里经常有人问 opencode memory 怎么用。opencode 的 Memory 是一套持久化机制，它可以让模型跨会话记住项目的约定、术语和偏好。

举个例子：我告诉它“本项目 API 返回格式统一为{ code, data, message }，代码生成时必须遵守”。这句话会被写入 memory 文件，之后新建会话时，它会在启动阶段自动加载这段记忆，然后所有新对话都遵循这个约定。

Memory 文件默认存在~/.local/share/opencode/memory/或者项目.opencode/memory/下，格式就是 Markdown。你可以手动编辑，也可以在对话里用指令写入。

使用上有个度的问题：Memory 不能塞太多，模型上下文窗口有限，记忆越多、被挤占的代码上下文就越多。我的习惯是：全局的编码规范和工具链配置放全局 memory，项目特有的架构决策和命名约定放项目 memory，而且定期清理过时条目。

5.4 oh-my-claudecode 与 superpowers 这些周边项目是什么

我在搜索词里看到 “opencode oh-my-claudecode” 和 “opencode 接入 superpower”，这里一并说清楚。oh-my-claudecode 原本是 Claude Code 的一套增强配置集，因为 opencode 兼容 Claude Code 的许多配置习惯，后来有人把这套增强配置移植到了 opencode 上。它主要提供的是更细粒度的角色设定、技能模板和命令行工具集合。而 superpowers（社区常写作 superpower）则是一套面向 AI Agent 的“能力增强包”，它通常以 skills 的形式分发，让 AI 执行任务时具备更规范的工作流，比如“先写测试再实现”这类开发方法论约束。

这类周边项目的价值在于省去你从零编写 skill 的工作量，但使用时要甄别质量。有些社区 skill 只是把大段 prompt 套壳，并没有真正绑定可执行的代码操作；而质量高的 skill 会包含 shell 脚本、文件读写逻辑和明确的判断条件。我建议先看看 skill 的源码，再决定是否放进项目，别盲目装一堆“花架子”。

6. 前端调试新姿势：用 Playwright 把 Bug 交给 AI 复现

6.1 为什么在 AI 编码工具里集成 Playwright 很重要

前端开发的 Bug 复现一直是 AI 辅助编程的薄弱环节。你让 AI 修一个样式错位的 Bug，它只能盯着代码猜测，但很多前端问题在浏览器渲染之后才会暴露。opencode 的解法是：引入 Playwright，让 AI 自己启动浏览器、打开页面、截图、读取控制台错误、然后结合代码进行修复。

这带来的变化是革命性的——AI 终于有了“眼睛”，能够看到真实渲染结果，而不是纯粹靠静态分析猜。

6.2 实战：用 opencode 定位并修复一个前端 Bug

我演示一个真实场景：一个 Vue 项目里的按钮在移动端点击无反应。传统做法是我自己跑 dev server，开 devtools，找半天原因。opencode + Playwright 的处理过程如下：

我先在对话里给出指令：

使用 Playwright 启动项目，以 iPhone 12 的视口尺寸打开首页，点击“提交”按钮，然后告诉我控制台有没有报错和无响应按钮的相关线索。

opencode 会调用 Playwright 工具，执行大致这样的流程：

1. 启动本地 dev server（自动读取 package.json 判断启动命令）；
2. 安装指定的 Playwright 浏览器环境（如果没有预装）；
3. 用设定好的设备描述符模拟移动端浏览器；
4. 打开页面、点击按钮、捕获 console 日志和页面截图；
5. 返回结果。

我实测的结果：它捕获到一条 JavaScript 异常——某个事件绑定函数里访问了未定义的属性，导致点击事件执行中断。修复过程也很快，AI 在定位到具体代码后直接生成了修复补丁，甚至给出了回归测试建议。

这套链路跑通后，前端 Bug 的排查效率提升非常明显。但也注意：Playwright 调试相对吃资源，首次启动浏览器下载可能耗时较长，在 CI 里要额外配置无头模式。

6.3 Playwright 调试时需要注意的配置项

如果你在 opencode 里使用 Playwright，建议在配置里指定浏览器数据目录和超时时间，避免默认配置引发一些奇怪的权限报错：

{ "playwright": { "timeout": 30000, "headless": true, "browserDataDir": ".playwright-data" } }

另外，有些政企项目的前端页面依赖内网 SSO 登录，Playwright 拿不到登录态会页面跳转。我的做法是：先手动用 Playwright 登录并保存 session 状态，再在 opencode 的测试指令中复用这个 session 文件，这样 AI 每次打开页面就能直接以登录态进入。

7. 编辑器里的全家桶：VS Code、JetBrains、桌面版怎么选

7.1 VS Code 插件与终端版的区别

opencode 的 VS Code 插件本质上是一个“终端前端的图形化封装”。安装后会在侧边栏出现一个会话面板，可以直接选择文件、查看 diff、执行 AI 生成的操作。它和终端版的区别是：IDE 插件能拿到的上下文更丰富——比如当前打开的文件、选中文本、IDE 的诊断信息。

我实测下来，VS Code 插件的体验在重构场景非常舒服。选中一段代码，AI 自动生成修改建议，我直接点击“应用”就能看到 diff。相比终端版需要输入路径和文件名，这个交互效率高了不少。

但如果你是重度快捷键用户，可能还是会回到终端版，因为 TUI 的响应速度更快，而且不会闪出 IDE 的加载动画。

7.2 JetBrains IDEA 插件：Java/Kotlin 开发者的正确姿势

社区搜索词里有 “opencode jetbrains idea 插件”“idea opencode 插件”，说明 Java 生态用户对这个工具也很关注。JetBrains 插件的能力和 VS Code 版类似，但对 Java/Kotlin 项目的支持更深入：它能直接读取 IDEA 的项目模型，识别类路径、模块依赖、运行配置。

在 IDEA 里使用 opencode 时，我建议配合上文的 LSP 配置，因为 IDEA 自身的语言服务已经在后台运行，二者冲突时可能导致 LSP 端口占用。如果遇到 “port already in use” 的报错，把自定义 LSP 配置里的端口改到 7000 以上即可。

7.3 桌面版（opencode desktop）适合什么场景

很多人看到 “opencode desktop” 以为是下一个 JetBrains 全家桶。其实桌面版更像是一个 AI 聊天客户端，不走终端、不依赖 IDE，打包成独立应用。适合的场景：

• 你不想要 IDE 的复杂界面，但需要图形化查看文件、代码块和 diff；
• 你需要长期运行一个 AI 会话，方便随时切换项目；
• 你希望把 AI 聊天记录、文件修改记录集中在一个应用里管理。

桌面版底层调用的还是 opencode 引擎，所以模型配置和终端版共用。它和 IDE 插件的选择取决于你的工作习惯：常驻桌面用桌面版，偶尔重构用 IDE 插件，自动化批处理用终端版。

7.4 我的使用组合建议

我自己目前的组合方式是：日常写代码用 VS Code 插件，批处理和脚本任务用终端版，开会演示代码功能用桌面版。三者共用同一套配置，模型配额也是同一个账号，不存在多端分家的困扰。

8. 横向对比与踩坑实录：opencode、Claude Code、Codex、pi 怎么选

8.1 四个主流 Agent 的差异

我最近被问到最多的问题就是：opencode、Claude Code、Codex CLI、pi 到底哪个好用。这里我给一个基于真实使用经验的对比，不代表绝对结论，因为工具迭代太快，说“谁永远最好”没有意义。

选型建议很直接：

• 如果你需要在多个模型之间切换、或者有私有化模型接入需求，优先 opencode；
• 如果你是 Claude 深度用户、日常任务简单清晰，Claude Code 的零配置体验更省心；
• 如果你主要在 GitHub Copilot 生态里，Codex CLI 跟 OpenAI 系的联动更顺；
• 如果你追求极简终端体验，pi 可以试试，但长远来看功能覆盖没有前两者全。

8.2 “unexpected server error” 和 “check server logs” 的处理

这个报错很常见，尤其在使用三方模型服务时：

error: unexpected server error. check server logs.

处理步骤我整理成一个排查链路：

1. 先看 opencode 自己能不能连通模型服务。在会话里发一句“你好”，如果连这句都报错，问题大概率在配置的 baseURL 或 API Key 上；
2. 用 curl 直接请求你配置的模型接口，验证服务端是否正常。如果 curl 正常、opencode 报错，说明可能是 opencode 的 SDK 版本跟模型接口不完全兼容，升级 opencode 版本试试；
3. 查看日志。终端版可以用opencode --log-level debug启动，日志会输出完整的请求与响应头，能直接看到上游返回的具体错误码；
4. 如果只在这个会话报错、重启后就好了，多半是上下文过长导致上游 reject，可以清理一下上下文或换一个上下文更长的模型。

8.3 final：几个值得记住的实操细节

最后分享几条我总结的实操经验，有些是我踩了大坑才记住的：

注意：opencode默认会读取当前目录下的.gitignore，如果项目根目录没有该文件，它可能会把.env文件里的密钥当上下文一并读取。这是安全隐患，建议在所有项目里强制加入.env到 gitignore，或使用 opencode 的 ignore 配置。

提示：如果你在 Windows PowerShell 里发现命令不生效，先确认你是在普通 PowerShell 而不是 PowerShell 7 里跑的。部分 Windows 安装脚本对 PowerShell 7 的 PATH 写入逻辑有兼容问题。

经验：在团队里推广 opencode 时，别一上来就让大家配复杂的 Skills 和 LSP。先让每个人跑通“安装 -> 对话 -> 改代码”这条主线，等大家习惯之后再逐步引入高级功能。工具链的陡峭坡度会把很多不熟悉 TUI 的同事劝退。

我个人现在的主力 AI 编码工具已经从 Claude Code 换成了 opencode，不是说它完美，而是它更符合我对“AI 协作开发”的理解：AI 不只是一个聊天的盒子，它应该能读代码、跑测试、看浏览器、记住约定，而我作为开发者，只需要给它一个明确的任务边界。这套工作流跑顺之后，写代码的体验确实变了——不再是“AI 帮我写函数”，而是“AI 帮我维护整个项目的认知”。

最后再分享一个小技巧：给 opencode 设一个全局的“欢迎指令”，让它在每次启动时先读取项目 README 和配置文件，然后向我汇报项目状态。这样做最大的好处是，即使隔了一周再回到一个项目，它也能快速把上下文拉回来，我不用浪费第一轮对话来“教它”项目是怎么回事。这个习惯我一直保留着，实测对长期项目的维护特别管用。