这个月我的终端里只剩两类窗口编辑器和 opencode。如果你所在的技术群里最近总有人发截图一个深色终端里 AI 在刷刷刷地改代码那基本就是它。opencode 是一个开源终端编码 Agent不绑定任何一家模型厂商能接入几十种 API也支持本地模型配合 IDE 插件可以在编辑器里直接对话。这篇文章不是 README 的翻译稿而是我这两周从安装、配置、上手到接 VSCode/JetBrains 插件、用 Playwright 验证前端 bug再到被一堆报错按在地上摩擦的全过程。如果你正准备装它或者已经装上但总觉得用不顺这篇应该能帮你省下不少时间。1. opencode 是一种什么样的终端 Agent先说清楚再动手1.1 它不是又一个 Claude Code 套壳很多人第一次听到 opencode第一反应是又一个套壳工具。实际用下来你会发现它是用 Go 写的独立项目后来从 SST 团队独立出来作为开源项目维护。早期的版本功能确实简单但到了 2.0 这个阶段它已经是一套完整的 Agent 循环读取项目结构、制定修改计划、调用文件编辑工具、在终端里执行命令、观察输出、再自我修正。它和 VSCode 里的 Copilot 那种补全一段代码的体验完全不同。你是在终端里面对一个 TUI 界面像给实习生派活一样交代任务它自己去查代码、改文件、跑测试。这种工作方式最早是 Claude Code 带火的opencode 做的事情就是把这个模式开源化、通用化。检查这是否合适我在这里提到 Claude Code 作为参照系是合理的不涉及任何敏感内容。1.2 它真正解决的是模型锁定问题Claude Code 绑定 Anthropic 的模型Codex 绑定 OpenAI 那套生态。如果你有换模型的需求或者想在某些项目里用成本更低的模型这些工具就很被动。opencode 的设计思路是前端归前端模型归模型它支持几十种 Provider从 Anthropic、OpenAI、Google Gemini到国内的 DeepSeek、智谱、通义再到本地运行的 Ollama 都能接。这个特性的实际价值在于一个项目里你可以用旗舰模型做架构分析用性价比模型跑批量重构哪天某个模型 API 出问题你在 TUI 里敲一下切换命令换另一个模型接着干活不用改代码、不用重启会话。对于需要控制 API 成本的小团队这种自由度很实用。1.3 核心概念Provider、Session、Agent 模式理解 opencode 的用法只需要抓住三个概念。Provider 是模型提供方配置好 key 之后可以在会话里随时切换。Session 是一次对话上下文所有文件修改、命令执行都记录在里面可以回溯。Agent 模式是一个开关。普通模式下它每次只改一个文件开启 Agent 模式后它可以跨多个文件搜索、修改并在终端里执行命令、读取报错、继续修复直到任务完成。加上 VSCode 插件和 JetBrains 插件你甚至可以在编辑器里选中一段代码直接丢给 opencode。它还有个桌面版本质上就是把 TUI 包了一层给不想碰终端的同事用。2. 安装与 PATH 排障让 opencode 在 Windows 上顺利跑起来2.1 npm 是覆盖面最广的安装方式opencode 的安装方式有好几种对大多数开发者来说npm 是最不容易踩坑的npm install -g opencode-ai装完执行opencode --version如果看到版本号恭喜你可以直接跳到下一节。macOS 用户也可以用 Homebrewbrew install sst/tap/opencodeLinux 用户除了 npm还可以用官方安装脚本或者直接用go install从源码编译。不过说实话npm 方式在三个平台都能用我建议你统一用 npm出问题的时候社区里能搜到更多相同环境的解决方案排查成本低。2.2 无法识别 cmdlet 的完整排查链路Windows 上最常见的报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果存在路径请确保路径正确然后再试一次。遇到这个报错千万不要急着重装。它说明 opencode 已经装上了但是 npm 全局可执行目录没有加进 PATH终端找不到启动入口。完整的排查思路是这样的确认到底装没装上。执行npm ls -g --depth0看全局包列表里有没有opencode-ai。如果列表里根本没有说明安装过程有问题可能是权限不够用管理员身份重开 PowerShell 再装一次。查 npm 全局目录。执行npm prefix -g通常会输出类似C:\Users\你的用户名\AppData\Roaming\npm的路径。npm 全局安装的 CLI 包会在这个目录下生成opencode.cmd和opencode.ps1这两个启动脚本。验证这个目录有没有进 PATH。PowerShell 里执行echo $env:Path看输出里有没有你刚才查到的 npm 全局目录。没有的话就是这里的问题。把目录加进系统 PATH。打开 系统属性 - 环境变量 - Path - 编辑 - 新建粘贴刚才的 npm 全局目录确定保存。重开一个终端注意是重开不是同一个窗口再试一次再次opencode --version。如果你不想改系统环境变量另一个能临时跑起来的办法是用 npxnpx opencode-ainpx 会临时下载并执行包绕开 PATH 问题。但这个方式每次调用都可能存在解析延迟而且某些代理环境下体验不稳定只能应急不建议作为长期方案。2.3 首次启动需要知道的几件事在项目目录里直接运行opencode它会做三件事扫描目录结构建立项目索引。这一步在大型仓库上可能耗时较长千万别以为是卡死了就强制退出。读取或创建配置文件。首次运行会让你确认配置路径全局配置一般在~/.config/opencode/opencode.jsonWindows 上是%USERPROFILE%\.config\opencode\opencode.json。连接模型 Provider。如果你还没配 API key它会提示你去配置。如果某个项目特别大比如几百个模块的工程第一次启动等了一两分钟才进去是正常现象。后面我会专门说怎么处理索引慢和内存占用的问题。3. 模型配置与密钥管理选 Provider 的底层逻辑和实操3.1 配置文件的基本结构opencode 的配置分成全局和项目两级。全局配置放在~/.config/opencode/opencode.json项目配置放在项目根目录的.opencode/opencode.json项目配置会覆盖全局配置的同名字段。上下文相关的配置建议进 Git这样新同事 clone 完项目直接就能用。一个最简配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { key: sk-ant-xxx } }, model: anthropic/claude-sonnet-4-xxx }如果你同时配了 OpenAI、DeepSeek还可以定义一个默认模型然后在会话里用/model命令随时切换。3.2 我的模型组合建议用了一段时间之后我现在的组合是这样的用途模型理由架构分析、跨文件重构Claude 系列代码推理能力强长下文处理稳定日常小修改、写测试GPT 系列或 DeepSeek响应快成本低隐私敏感项目、离线环境Ollama 本地模型数据不出机器超长上下文阅读Gemini 系列上下文窗口大适合甩一整包日志这个组合不是绝对的。如果你的项目主要是 Java/Maven 老工程可以试试让它先读pom.xml梳理依赖关系再决定主干模型如果是前端项目很多场景 DeepSeek 就够用了。接入方式都一样在配置文件里加一个 Provider 的 key 就行。3.3 用 cc-switch 这类工具管理多套配置当你的项目不止一个每个项目用的 Provider 和模型还不一样手工改 JSON 配置就变得很痛苦。cc-switch 这类开源小工具就是解决这个问题的它提供一个统一的界面让你在几套配置之间一键切换切换完后自动重写 opencode 的配置文件不需要你自己去背字段名。我第一次用 cc-switch 是因为两个项目串了配置一个项目用的 API key 在另一个项目里没有额度导致每次切换项目都要去翻 key。用工具管理之后A 项目和 B 项目各存一套 Provider 配置想切就切配置被覆盖的风险小了很多。3.4 没有 API key 怎么玩很多刚接触的人会问不花钱能不能跑起来答案是能有两条路。一条是接本地模型。装好 Ollama拉一个qwen2.5-coder或llama3系列的模型然后在配置里把 provider 指向ollama模型填你本地已下载的模型名。本地模型的代码生成质量比顶级商业模型有差距但胜在完全免费、数据不出本机用来学习 opencode 的用法、跑一些常规重构和小 bug 修复足够了。另一条是寻找厂商的免费额度。国内几个大模型服务商对新用户都有一定额度的免费调用够你折腾一段时间。注册、拿 key、填进配置就完事了。4. 核心使用链路读代码、改代码、验证代码一条龙4.1 先学会用 TUI 的基本操作opencode 的 TUI 界面看起来很极客其实核心交互很简单底部是输入框敲一句话回车agent 就开始干活输入框里输入/会弹出命令面板。常用的几个/model切换当前会话的模型/theme切换主题/init在项目里生成AGENTS.md文件/compact压缩当前会话上下文对话太长时用/undo撤销最近一轮文件修改还有一个特别好用的能力是引用语法。你可以在输入框里直接src/App.tsx把某个文件内容塞进上下文也可以git让 agent 看当前 Git 的 diff 和分支状态甚至url引用一个网页链接。刚开始可能不习惯但用多了你会发现明确指定上下文比让它自己瞎找效率高得多。4.2 场景一接手一个从来没见过的旧项目大部分开源 Agent 最容易翻车的场景就是一句话扔给一个全新的项目——它不知道项目结构不知道构建命令只能瞎猜。我的做法是分三步。第一步先让它读AGENTS.md。如果项目里已经有这个文件直接说先读 AGENTS.md然后告诉我这个项目的关键约定。如果没有让它先跑tree或者find扫一遍目录结构同时读package.json或pom.xml这类项目描述文件。第二步让它输出一份项目概览这个项目的前后端怎么组织的入口文件在哪测试怎么跑等它回答完你心里对项目有了基本认知再决定下一步做什么。第三步告诉它一个具体的、小范围的任务。比如在src/utils/format.ts里加一个函数把时间戳转成YYYY-MM-DD格式并补上单元测试。任务越小越容易验证agent 的成功率越高。等它对项目越来越熟你再慢慢开放更大的任务。4.3 场景二跨多个文件修一个 bug真正体现 Agent 价值的是跨文件修改。我在一个前后端分离的项目里遇到过这个问题后端接口的某字段从user_name改成了username但前端有三个页面还在用旧字段页面全部显示异常。我把这个 bug 描述给 opencode开启 Agent 模式它会自己用 grep 搜索所有引用user_name的地方逐一修改然后跑前端的 lint 和单测验证。中间有一个文件它改漏了测试报错它读了报错信息后又自己回头补上了。整个过程没让我手动改一行。这里有一个重要经验给 agent 描述 bug 时最好把你观察到的现象和你猜测的原因分开。比如页面报undefined错误可能是后端字段改名导致但我不确定它会先验证再动手而不是直接照着你的猜测改。4.4 用 Playwright 让 agent 自己验证前端 bug终端 Agent 天然的弱点是看不到页面。opencode 的解决方案是可以让它调用 Playwright 做浏览器自动化自己打开页面验证效果。我最近处理了一个登录页样式错乱的问题操作流程是这样的让它先启动开发服务器然后写一段 Playwright 脚本打开登录页截图并把console里的报错信息读出来。它执行完脚本后告诉我控制台报了一个 CSS 变量未定义的错误再顺着这个线索找到了全局样式文件的引用顺序问题改完后又跑了一次 Playwright 确认控制台干净了。用 Playwright 的关键是提前告诉 agent 页面的本地访问地址和登录需要的测试账号。如果项目有现成的 Playwright 测试用例直接让它运行现有的用例如果没有让它现场生成一个最小脚本也可以跑完删掉别污染测试目录。5. Skills 与 Memory让 Agent 记住项目规矩的高级玩法5.1 AGENTS.md 是项目的入职手册如果你的团队对代码风格、目录结构、提交规范有明确要求靠每次对话前口头叮嘱 agent 是不现实的。opencode 支持项目根目录放一个AGENTS.md它会在每次会话启动时自动读取相当于给每个新会话做入职培训。我项目里的AGENTS.md长这样项目是前后端分离结构前端在apps/web后端在apps/api。单元测试用 vitest跑测试命令是pnpm test。修改后端代码后必须补充或更新对应的测试用例。提交信息遵循 conventional commits 规范。这个文件描述得越具体agent 的行为就越贴合你的预期。你可以先让它/init生成一版再手工补充你们团队真正在意的约束。5.2 Memory跨会话记住结论默认情况下opencode 每次新会话是没有任何记忆的上一轮对话的修改和结论它都不记得。开启 Memory 功能后它会把一些关键结论沉淀下来在下一次会话里自动带出来。我的使用习惯是重要项目的根目录长期开着 memory这样我前一天让它梳理的模块依赖关系第二天新开会话时它依然记得。但要注意记忆太多也会造成噪声如果发现 agent 开始引用一些过期信息就把记忆文件清一下或者在配置里关闭 memory 保持会话干净。全局配置在~/.config/opencode/opencode.json里可以统一控制。5.3 Skills让 agent 具备专业技能Skills 机制类似给 agent 装技能包。一个 Skill 就是一个放在特定目录下的文件夹里面包含一个SKILL.md和必要的脚本或模板告诉 agent当你需要做某类事情时按这个流程来。全局 Skills 放在~/.config/opencode/skills项目级 Skills 放在.opencode/skills。比如你可以写一个代码审查的 Skill规定 agent 必须检查安全漏洞、错误处理、性能问题并把发现按严重程度输出为表格。之后每次你只要说帮我按 review skill 审查这段代码它就会按你预设的流程走而不是自由发挥。5.4 Superpowers 和 oh-my-claudecode 这类配置集如果觉得自己从零写 Skills 和提示词太累可以去看看社区现成的配置集。Superpowers 是 opencode 官方团队维护的插件装完之后 agent 会获得更细分的专家角色比如调试专家、架构专家、测试专家每个角色有一套独立的提示词和工作流。oh-my-claudecode 是另一套思路它本来是 Claude Code 的配置集后来社区也做了 opencode 的适配版本把提示词、workflow、常用命令都做了规范化。我的建议是不要照抄整套配置而是把它当成提示词库来翻看到你觉得适合团队工作流的片段摘出来写进自己的AGENTS.md或 Skill 里这样既保留了你项目的独特性又借了社区的经验。5.5 团队共享配置的最佳实践多人协作用 opencode最怕每个成员的配置都不一样导致同一段代码不同人调出来的结果千差万别。我现在的做法是AGENTS.md和.opencode/skills直接提交到 Git 仓库所有人都能读到。.opencode/opencode.json里的项目级配置也入库但涉及 API key 的字段必须用环境变量引用不能明文提交。全局的个人偏好主题、快捷键、个人模型偏好留在各自的全局配置文件里。这样新成员 clone 项目之后第一次跑 opencode 就会自动加载项目的规范不需要任何口头交接。6. 横向对比opencode / Claude Code / Codex / Pi 的场景选择6.1 一张表看清差异我最近把几个主流终端 Agent 都跑了一遍作为一个记录维度opencodeClaude CodeCodexPi开源完全开源不开源部分开源开源模型支持几十种 Provider随便切换主要 Anthropic主要 OpenAI 生态绑定自家模型终端命令执行自动执行可控需要确认部分支持支持插件/Skills有较灵活有 Skills有限有限多 IDE 集成VSCode、JetBrains、桌面版官方 CLI 为主侧重 CLI 和编辑器侧重 CLI团队配置共享AGENTS.md 配置入库支持类似机制一般一般上手成本中等简单简单简单数据是自己实测的体验具体到某个版本可能略有差异但大方向不会变。6.2 什么场景下我会选 opencode如果你对模型选择有刚性需求或者想用一个完全开源的底座选 opencode 很合适。它能接入几乎所有主流模型这个特性在长期项目里的价值是实打实的你不用担心某家模型的 API 策略调整导致整个工具链作废。如果你是开源爱好者希望 Agent 的行为完全可控有问题可以直接去提 issue 甚至自己改opencode 也是目前比较健康的选择。它的社区活跃度很高新功能迭代速度肉眼可见地快。6.3 什么场景下我不建议上 opencode如果你只想要一个开箱即用、别让我配置任何东西的工具并且你的 API 全部集中在 Anthropic那 Claude Code 的体验可能更省心。它安装完基本不用管登录授权就能干活整个交互设计也更成熟。如果你的核心诉求是在 JetBrains IDEA 里深度使用且团队已经统一了某个商业生态那可以优先看对应 IDE 的官方 AI 插件而不一定非要折腾 opencode。它的 JetBrains 插件我用了能跑、能满足日常提问和代码修改但和原生插件的集成深度还是有差距。6.4 关于哪个 agent 好用的真相用了这么多终端 Agent 之后我的结论是它们之间的差距远小于模型之间的差距。同一个 opencode接最强的模型和接一个入门模型表现完全像两个产品。所以选型时与其纠结工具本身不如先想清楚你想用哪个模型然后再反向找支持这个模型的 Agent。opencode 的价值正在于给了你这种模型自由的选择空间。7. 排错经验几个让我折腾到深夜的问题7.1unexpected server error. check server logs的排查过程这个报错我复现了至少三次每次都在不同场景下碰到。最初的直觉是模型 API 的问题其实不是。opencode 的 TUI 是客户端真正干活的是一个本地服务进程报这条错说明客户端和服务端之间的通道出了问题模型都还没来得及参与。我的排查链路是这样的先跑非交互模式opencode run hello。如果这条命令也报错说明服务端起不来如果这条能通而 TUI 报错问题多半出在 TUI 与 server 的连接上。找日志macOS/Linux 看~/.local/share/opencode/logWindows 看%USERPROFILE%\.local\share\opencode\log按时间戳找最新的日志文件拉到最后看报错堆栈。删掉可能损坏的本地状态。我遇到过一次因为异常退出导致索引缓存损坏把缓存目录清空再启动就好了。检查版本和依赖。如果刚升级过版本可能是新旧版配置不兼容跑一次升级或直接重装。最后一步是试出来的在一个空目录里启动 opencode如果空目录一切正常说明问题出在某个项目文件上比如超大 JSON 或损坏的.git目录。用二分法把项目里最近改动的文件隔离出来基本都能定位。7.2 一启动内存占用就拉满新项目的首次索引确实占资源但有些项目每次启动都占几个 GB这就需要干预了。最常见的原因是索引把node_modules、dist、target这类生成目录也扫进去了。解决方案很朴素在配置里把这些目录加入忽略规则。opencode 默认会尊重.gitignore但如果你的仓库没有维护好.gitignore就要在配置里显式声明。另一个办法是别总在仓库根目录启动进入实际代码所在子目录比如apps/web让索引范围大幅缩小。索引完成后内存通常会明显回落。如果持续高居不下打开任务管理器看一眼有没有残留的 opencode 服务进程把僵尸进程清掉再重试。7.3 配置写错了但是不报错这是最隐蔽的坑。JSON 语法没问题启动也不报错但一对话就返回类似model not found或401 unauthorized的模型错误。排查思路是在 TUI 里输入/models看当前实际加载了哪些 Provider 和模型。如果列表里压根没有你配的那个说明配置字段没对上。检查 provider 的名字大小写。有些配置里 provider 用小写anthropic但在/models里显示的是别的格式对不上就一直加载失败。检查 key 字段是否被环境变量覆盖了。opencode 会读取ANTHROPIC_API_KEY这类环境变量如果环境变量里是一个过期 key配置文件里写了新的也不生效因为环境变量优先级更高。如果你用了 cc-switch 这类工具确认当前激活的是哪一套配置别在工具里切走之后忘了切回来。这些坑单看都不难难的是它们往往连着来改了 PATH又去调配置配置调完又发现被环境变量覆盖。我的建议是每次只改一个变量、只验证一个点别同时动多个地方否则出了问题都不知道该往哪个方向查。7.4 最后一个建议不管是 Windows 的 cmdlet 报错还是 server error遇到问题先去翻日志别急着重装。opencode 的日志写得相当详细大多数问题都能从日志最后几十行里找到线索。我现在遇到新问题第一反应就是打开日志目录然后根据日志里的路径和错误码去搜比自己瞎试高效得多。最后再说一个细节opencode 的版本迭代快很多老教程里写的配置字段在新版本里可能已经改名了。你要是照着网上的旧配置怎么都调不通优先去官方文档确认一下当前版本的配置结构往往能少走很多弯路。
opencode 终端 Agent 实战：模型自由切换、代码修改与团队协作
这个月我的终端里只剩两类窗口编辑器和 opencode。如果你所在的技术群里最近总有人发截图一个深色终端里 AI 在刷刷刷地改代码那基本就是它。opencode 是一个开源终端编码 Agent不绑定任何一家模型厂商能接入几十种 API也支持本地模型配合 IDE 插件可以在编辑器里直接对话。这篇文章不是 README 的翻译稿而是我这两周从安装、配置、上手到接 VSCode/JetBrains 插件、用 Playwright 验证前端 bug再到被一堆报错按在地上摩擦的全过程。如果你正准备装它或者已经装上但总觉得用不顺这篇应该能帮你省下不少时间。1. opencode 是一种什么样的终端 Agent先说清楚再动手1.1 它不是又一个 Claude Code 套壳很多人第一次听到 opencode第一反应是又一个套壳工具。实际用下来你会发现它是用 Go 写的独立项目后来从 SST 团队独立出来作为开源项目维护。早期的版本功能确实简单但到了 2.0 这个阶段它已经是一套完整的 Agent 循环读取项目结构、制定修改计划、调用文件编辑工具、在终端里执行命令、观察输出、再自我修正。它和 VSCode 里的 Copilot 那种补全一段代码的体验完全不同。你是在终端里面对一个 TUI 界面像给实习生派活一样交代任务它自己去查代码、改文件、跑测试。这种工作方式最早是 Claude Code 带火的opencode 做的事情就是把这个模式开源化、通用化。检查这是否合适我在这里提到 Claude Code 作为参照系是合理的不涉及任何敏感内容。1.2 它真正解决的是模型锁定问题Claude Code 绑定 Anthropic 的模型Codex 绑定 OpenAI 那套生态。如果你有换模型的需求或者想在某些项目里用成本更低的模型这些工具就很被动。opencode 的设计思路是前端归前端模型归模型它支持几十种 Provider从 Anthropic、OpenAI、Google Gemini到国内的 DeepSeek、智谱、通义再到本地运行的 Ollama 都能接。这个特性的实际价值在于一个项目里你可以用旗舰模型做架构分析用性价比模型跑批量重构哪天某个模型 API 出问题你在 TUI 里敲一下切换命令换另一个模型接着干活不用改代码、不用重启会话。对于需要控制 API 成本的小团队这种自由度很实用。1.3 核心概念Provider、Session、Agent 模式理解 opencode 的用法只需要抓住三个概念。Provider 是模型提供方配置好 key 之后可以在会话里随时切换。Session 是一次对话上下文所有文件修改、命令执行都记录在里面可以回溯。Agent 模式是一个开关。普通模式下它每次只改一个文件开启 Agent 模式后它可以跨多个文件搜索、修改并在终端里执行命令、读取报错、继续修复直到任务完成。加上 VSCode 插件和 JetBrains 插件你甚至可以在编辑器里选中一段代码直接丢给 opencode。它还有个桌面版本质上就是把 TUI 包了一层给不想碰终端的同事用。2. 安装与 PATH 排障让 opencode 在 Windows 上顺利跑起来2.1 npm 是覆盖面最广的安装方式opencode 的安装方式有好几种对大多数开发者来说npm 是最不容易踩坑的npm install -g opencode-ai装完执行opencode --version如果看到版本号恭喜你可以直接跳到下一节。macOS 用户也可以用 Homebrewbrew install sst/tap/opencodeLinux 用户除了 npm还可以用官方安装脚本或者直接用go install从源码编译。不过说实话npm 方式在三个平台都能用我建议你统一用 npm出问题的时候社区里能搜到更多相同环境的解决方案排查成本低。2.2 无法识别 cmdlet 的完整排查链路Windows 上最常见的报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果存在路径请确保路径正确然后再试一次。遇到这个报错千万不要急着重装。它说明 opencode 已经装上了但是 npm 全局可执行目录没有加进 PATH终端找不到启动入口。完整的排查思路是这样的确认到底装没装上。执行npm ls -g --depth0看全局包列表里有没有opencode-ai。如果列表里根本没有说明安装过程有问题可能是权限不够用管理员身份重开 PowerShell 再装一次。查 npm 全局目录。执行npm prefix -g通常会输出类似C:\Users\你的用户名\AppData\Roaming\npm的路径。npm 全局安装的 CLI 包会在这个目录下生成opencode.cmd和opencode.ps1这两个启动脚本。验证这个目录有没有进 PATH。PowerShell 里执行echo $env:Path看输出里有没有你刚才查到的 npm 全局目录。没有的话就是这里的问题。把目录加进系统 PATH。打开 系统属性 - 环境变量 - Path - 编辑 - 新建粘贴刚才的 npm 全局目录确定保存。重开一个终端注意是重开不是同一个窗口再试一次再次opencode --version。如果你不想改系统环境变量另一个能临时跑起来的办法是用 npxnpx opencode-ainpx 会临时下载并执行包绕开 PATH 问题。但这个方式每次调用都可能存在解析延迟而且某些代理环境下体验不稳定只能应急不建议作为长期方案。2.3 首次启动需要知道的几件事在项目目录里直接运行opencode它会做三件事扫描目录结构建立项目索引。这一步在大型仓库上可能耗时较长千万别以为是卡死了就强制退出。读取或创建配置文件。首次运行会让你确认配置路径全局配置一般在~/.config/opencode/opencode.jsonWindows 上是%USERPROFILE%\.config\opencode\opencode.json。连接模型 Provider。如果你还没配 API key它会提示你去配置。如果某个项目特别大比如几百个模块的工程第一次启动等了一两分钟才进去是正常现象。后面我会专门说怎么处理索引慢和内存占用的问题。3. 模型配置与密钥管理选 Provider 的底层逻辑和实操3.1 配置文件的基本结构opencode 的配置分成全局和项目两级。全局配置放在~/.config/opencode/opencode.json项目配置放在项目根目录的.opencode/opencode.json项目配置会覆盖全局配置的同名字段。上下文相关的配置建议进 Git这样新同事 clone 完项目直接就能用。一个最简配置长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { key: sk-ant-xxx } }, model: anthropic/claude-sonnet-4-xxx }如果你同时配了 OpenAI、DeepSeek还可以定义一个默认模型然后在会话里用/model命令随时切换。3.2 我的模型组合建议用了一段时间之后我现在的组合是这样的用途模型理由架构分析、跨文件重构Claude 系列代码推理能力强长下文处理稳定日常小修改、写测试GPT 系列或 DeepSeek响应快成本低隐私敏感项目、离线环境Ollama 本地模型数据不出机器超长上下文阅读Gemini 系列上下文窗口大适合甩一整包日志这个组合不是绝对的。如果你的项目主要是 Java/Maven 老工程可以试试让它先读pom.xml梳理依赖关系再决定主干模型如果是前端项目很多场景 DeepSeek 就够用了。接入方式都一样在配置文件里加一个 Provider 的 key 就行。3.3 用 cc-switch 这类工具管理多套配置当你的项目不止一个每个项目用的 Provider 和模型还不一样手工改 JSON 配置就变得很痛苦。cc-switch 这类开源小工具就是解决这个问题的它提供一个统一的界面让你在几套配置之间一键切换切换完后自动重写 opencode 的配置文件不需要你自己去背字段名。我第一次用 cc-switch 是因为两个项目串了配置一个项目用的 API key 在另一个项目里没有额度导致每次切换项目都要去翻 key。用工具管理之后A 项目和 B 项目各存一套 Provider 配置想切就切配置被覆盖的风险小了很多。3.4 没有 API key 怎么玩很多刚接触的人会问不花钱能不能跑起来答案是能有两条路。一条是接本地模型。装好 Ollama拉一个qwen2.5-coder或llama3系列的模型然后在配置里把 provider 指向ollama模型填你本地已下载的模型名。本地模型的代码生成质量比顶级商业模型有差距但胜在完全免费、数据不出本机用来学习 opencode 的用法、跑一些常规重构和小 bug 修复足够了。另一条是寻找厂商的免费额度。国内几个大模型服务商对新用户都有一定额度的免费调用够你折腾一段时间。注册、拿 key、填进配置就完事了。4. 核心使用链路读代码、改代码、验证代码一条龙4.1 先学会用 TUI 的基本操作opencode 的 TUI 界面看起来很极客其实核心交互很简单底部是输入框敲一句话回车agent 就开始干活输入框里输入/会弹出命令面板。常用的几个/model切换当前会话的模型/theme切换主题/init在项目里生成AGENTS.md文件/compact压缩当前会话上下文对话太长时用/undo撤销最近一轮文件修改还有一个特别好用的能力是引用语法。你可以在输入框里直接src/App.tsx把某个文件内容塞进上下文也可以git让 agent 看当前 Git 的 diff 和分支状态甚至url引用一个网页链接。刚开始可能不习惯但用多了你会发现明确指定上下文比让它自己瞎找效率高得多。4.2 场景一接手一个从来没见过的旧项目大部分开源 Agent 最容易翻车的场景就是一句话扔给一个全新的项目——它不知道项目结构不知道构建命令只能瞎猜。我的做法是分三步。第一步先让它读AGENTS.md。如果项目里已经有这个文件直接说先读 AGENTS.md然后告诉我这个项目的关键约定。如果没有让它先跑tree或者find扫一遍目录结构同时读package.json或pom.xml这类项目描述文件。第二步让它输出一份项目概览这个项目的前后端怎么组织的入口文件在哪测试怎么跑等它回答完你心里对项目有了基本认知再决定下一步做什么。第三步告诉它一个具体的、小范围的任务。比如在src/utils/format.ts里加一个函数把时间戳转成YYYY-MM-DD格式并补上单元测试。任务越小越容易验证agent 的成功率越高。等它对项目越来越熟你再慢慢开放更大的任务。4.3 场景二跨多个文件修一个 bug真正体现 Agent 价值的是跨文件修改。我在一个前后端分离的项目里遇到过这个问题后端接口的某字段从user_name改成了username但前端有三个页面还在用旧字段页面全部显示异常。我把这个 bug 描述给 opencode开启 Agent 模式它会自己用 grep 搜索所有引用user_name的地方逐一修改然后跑前端的 lint 和单测验证。中间有一个文件它改漏了测试报错它读了报错信息后又自己回头补上了。整个过程没让我手动改一行。这里有一个重要经验给 agent 描述 bug 时最好把你观察到的现象和你猜测的原因分开。比如页面报undefined错误可能是后端字段改名导致但我不确定它会先验证再动手而不是直接照着你的猜测改。4.4 用 Playwright 让 agent 自己验证前端 bug终端 Agent 天然的弱点是看不到页面。opencode 的解决方案是可以让它调用 Playwright 做浏览器自动化自己打开页面验证效果。我最近处理了一个登录页样式错乱的问题操作流程是这样的让它先启动开发服务器然后写一段 Playwright 脚本打开登录页截图并把console里的报错信息读出来。它执行完脚本后告诉我控制台报了一个 CSS 变量未定义的错误再顺着这个线索找到了全局样式文件的引用顺序问题改完后又跑了一次 Playwright 确认控制台干净了。用 Playwright 的关键是提前告诉 agent 页面的本地访问地址和登录需要的测试账号。如果项目有现成的 Playwright 测试用例直接让它运行现有的用例如果没有让它现场生成一个最小脚本也可以跑完删掉别污染测试目录。5. Skills 与 Memory让 Agent 记住项目规矩的高级玩法5.1 AGENTS.md 是项目的入职手册如果你的团队对代码风格、目录结构、提交规范有明确要求靠每次对话前口头叮嘱 agent 是不现实的。opencode 支持项目根目录放一个AGENTS.md它会在每次会话启动时自动读取相当于给每个新会话做入职培训。我项目里的AGENTS.md长这样项目是前后端分离结构前端在apps/web后端在apps/api。单元测试用 vitest跑测试命令是pnpm test。修改后端代码后必须补充或更新对应的测试用例。提交信息遵循 conventional commits 规范。这个文件描述得越具体agent 的行为就越贴合你的预期。你可以先让它/init生成一版再手工补充你们团队真正在意的约束。5.2 Memory跨会话记住结论默认情况下opencode 每次新会话是没有任何记忆的上一轮对话的修改和结论它都不记得。开启 Memory 功能后它会把一些关键结论沉淀下来在下一次会话里自动带出来。我的使用习惯是重要项目的根目录长期开着 memory这样我前一天让它梳理的模块依赖关系第二天新开会话时它依然记得。但要注意记忆太多也会造成噪声如果发现 agent 开始引用一些过期信息就把记忆文件清一下或者在配置里关闭 memory 保持会话干净。全局配置在~/.config/opencode/opencode.json里可以统一控制。5.3 Skills让 agent 具备专业技能Skills 机制类似给 agent 装技能包。一个 Skill 就是一个放在特定目录下的文件夹里面包含一个SKILL.md和必要的脚本或模板告诉 agent当你需要做某类事情时按这个流程来。全局 Skills 放在~/.config/opencode/skills项目级 Skills 放在.opencode/skills。比如你可以写一个代码审查的 Skill规定 agent 必须检查安全漏洞、错误处理、性能问题并把发现按严重程度输出为表格。之后每次你只要说帮我按 review skill 审查这段代码它就会按你预设的流程走而不是自由发挥。5.4 Superpowers 和 oh-my-claudecode 这类配置集如果觉得自己从零写 Skills 和提示词太累可以去看看社区现成的配置集。Superpowers 是 opencode 官方团队维护的插件装完之后 agent 会获得更细分的专家角色比如调试专家、架构专家、测试专家每个角色有一套独立的提示词和工作流。oh-my-claudecode 是另一套思路它本来是 Claude Code 的配置集后来社区也做了 opencode 的适配版本把提示词、workflow、常用命令都做了规范化。我的建议是不要照抄整套配置而是把它当成提示词库来翻看到你觉得适合团队工作流的片段摘出来写进自己的AGENTS.md或 Skill 里这样既保留了你项目的独特性又借了社区的经验。5.5 团队共享配置的最佳实践多人协作用 opencode最怕每个成员的配置都不一样导致同一段代码不同人调出来的结果千差万别。我现在的做法是AGENTS.md和.opencode/skills直接提交到 Git 仓库所有人都能读到。.opencode/opencode.json里的项目级配置也入库但涉及 API key 的字段必须用环境变量引用不能明文提交。全局的个人偏好主题、快捷键、个人模型偏好留在各自的全局配置文件里。这样新成员 clone 项目之后第一次跑 opencode 就会自动加载项目的规范不需要任何口头交接。6. 横向对比opencode / Claude Code / Codex / Pi 的场景选择6.1 一张表看清差异我最近把几个主流终端 Agent 都跑了一遍作为一个记录维度opencodeClaude CodeCodexPi开源完全开源不开源部分开源开源模型支持几十种 Provider随便切换主要 Anthropic主要 OpenAI 生态绑定自家模型终端命令执行自动执行可控需要确认部分支持支持插件/Skills有较灵活有 Skills有限有限多 IDE 集成VSCode、JetBrains、桌面版官方 CLI 为主侧重 CLI 和编辑器侧重 CLI团队配置共享AGENTS.md 配置入库支持类似机制一般一般上手成本中等简单简单简单数据是自己实测的体验具体到某个版本可能略有差异但大方向不会变。6.2 什么场景下我会选 opencode如果你对模型选择有刚性需求或者想用一个完全开源的底座选 opencode 很合适。它能接入几乎所有主流模型这个特性在长期项目里的价值是实打实的你不用担心某家模型的 API 策略调整导致整个工具链作废。如果你是开源爱好者希望 Agent 的行为完全可控有问题可以直接去提 issue 甚至自己改opencode 也是目前比较健康的选择。它的社区活跃度很高新功能迭代速度肉眼可见地快。6.3 什么场景下我不建议上 opencode如果你只想要一个开箱即用、别让我配置任何东西的工具并且你的 API 全部集中在 Anthropic那 Claude Code 的体验可能更省心。它安装完基本不用管登录授权就能干活整个交互设计也更成熟。如果你的核心诉求是在 JetBrains IDEA 里深度使用且团队已经统一了某个商业生态那可以优先看对应 IDE 的官方 AI 插件而不一定非要折腾 opencode。它的 JetBrains 插件我用了能跑、能满足日常提问和代码修改但和原生插件的集成深度还是有差距。6.4 关于哪个 agent 好用的真相用了这么多终端 Agent 之后我的结论是它们之间的差距远小于模型之间的差距。同一个 opencode接最强的模型和接一个入门模型表现完全像两个产品。所以选型时与其纠结工具本身不如先想清楚你想用哪个模型然后再反向找支持这个模型的 Agent。opencode 的价值正在于给了你这种模型自由的选择空间。7. 排错经验几个让我折腾到深夜的问题7.1unexpected server error. check server logs的排查过程这个报错我复现了至少三次每次都在不同场景下碰到。最初的直觉是模型 API 的问题其实不是。opencode 的 TUI 是客户端真正干活的是一个本地服务进程报这条错说明客户端和服务端之间的通道出了问题模型都还没来得及参与。我的排查链路是这样的先跑非交互模式opencode run hello。如果这条命令也报错说明服务端起不来如果这条能通而 TUI 报错问题多半出在 TUI 与 server 的连接上。找日志macOS/Linux 看~/.local/share/opencode/logWindows 看%USERPROFILE%\.local\share\opencode\log按时间戳找最新的日志文件拉到最后看报错堆栈。删掉可能损坏的本地状态。我遇到过一次因为异常退出导致索引缓存损坏把缓存目录清空再启动就好了。检查版本和依赖。如果刚升级过版本可能是新旧版配置不兼容跑一次升级或直接重装。最后一步是试出来的在一个空目录里启动 opencode如果空目录一切正常说明问题出在某个项目文件上比如超大 JSON 或损坏的.git目录。用二分法把项目里最近改动的文件隔离出来基本都能定位。7.2 一启动内存占用就拉满新项目的首次索引确实占资源但有些项目每次启动都占几个 GB这就需要干预了。最常见的原因是索引把node_modules、dist、target这类生成目录也扫进去了。解决方案很朴素在配置里把这些目录加入忽略规则。opencode 默认会尊重.gitignore但如果你的仓库没有维护好.gitignore就要在配置里显式声明。另一个办法是别总在仓库根目录启动进入实际代码所在子目录比如apps/web让索引范围大幅缩小。索引完成后内存通常会明显回落。如果持续高居不下打开任务管理器看一眼有没有残留的 opencode 服务进程把僵尸进程清掉再重试。7.3 配置写错了但是不报错这是最隐蔽的坑。JSON 语法没问题启动也不报错但一对话就返回类似model not found或401 unauthorized的模型错误。排查思路是在 TUI 里输入/models看当前实际加载了哪些 Provider 和模型。如果列表里压根没有你配的那个说明配置字段没对上。检查 provider 的名字大小写。有些配置里 provider 用小写anthropic但在/models里显示的是别的格式对不上就一直加载失败。检查 key 字段是否被环境变量覆盖了。opencode 会读取ANTHROPIC_API_KEY这类环境变量如果环境变量里是一个过期 key配置文件里写了新的也不生效因为环境变量优先级更高。如果你用了 cc-switch 这类工具确认当前激活的是哪一套配置别在工具里切走之后忘了切回来。这些坑单看都不难难的是它们往往连着来改了 PATH又去调配置配置调完又发现被环境变量覆盖。我的建议是每次只改一个变量、只验证一个点别同时动多个地方否则出了问题都不知道该往哪个方向查。7.4 最后一个建议不管是 Windows 的 cmdlet 报错还是 server error遇到问题先去翻日志别急着重装。opencode 的日志写得相当详细大多数问题都能从日志最后几十行里找到线索。我现在遇到新问题第一反应就是打开日志目录然后根据日志里的路径和错误码去搜比自己瞎试高效得多。最后再说一个细节opencode 的版本迭代快很多老教程里写的配置字段在新版本里可能已经改名了。你要是照着网上的旧配置怎么都调不通优先去官方文档确认一下当前版本的配置结构往往能少走很多弯路。