最近我在主力笔记本上装了一个有点上头的工具叫 opencode。如果你平时用 ChatGPT、Claude 之类的大模型写代码应该能快速理解它的定位它不是聊天窗口里的补全工具而是直接跑在终端里的 AI 编码代理提供一个类似 REPL 的交互环境让模型自己去读项目、改代码、跑命令、查报错。说白了它更像是一个能跟你并排坐在电脑前的结对程序员而不是一个只会帮你续写函数的自动补全插件。我最初注意到它是因为社区里好几个人都在拿它跟 Claude Code、Codex CLI 对比讨论“终端里到底哪个 agent 更好用”。opencode 这个名字听着挺大气其实是一个开源社区项目并不是哪家大厂官方的产品。它背后挂的是各家大模型 API支持 OpenAI、Anthropic、Google、本地 Ollama 等等而且把 Skills、Memory、浏览器自动化这些能力都整合进了同一个命令行工具里。这篇文章我就把自己从安装到日常使用的全过程摊开讲一遍包括配置模型、写 Skills、调 Playwright、接 IDE 插件、处理各种报错最后再聊聊它和另外两个主流终端 agent 的区别。不想看废话的可以直接跳到对应章节对照抄。1. opencode 到底是什么一个跑在终端里的 AI 编码代理1.1 核心定位与亮点如果你已经用过 Claude Code那 opencode 的上手成本几乎为零。它做的事情跟 Claude Code 类似你在终端里启动它会给它一个项目目录然后它会读文件、分析代码、执行命令、改代码、跑测试整个过程是半自动的。你不需要手把手把错误信息复制粘贴给它它会自己看。跟普通 AI 编程插件相比opencode 最大的差异在于“代理Agent”式的工作方式。常规补全工具是“你写一句它补一句”遇到问题还得你手动把报错贴进网页。opencode 则是把任务交出去它会自己规划步骤先看目录结构再读相关源码然后改文件最后跑测试验证。这个闭环一旦跑顺效率提升非常明显。另一个亮点是它的可扩展性。opencode 不是只靠一个聊天窗口打天下它有 Skills 机制允许你写自然语言指令模板把整个项目规范灌进去有 Memory 机制能跨会话记住项目背景和你的偏好还能用 Playwright 驱动真实浏览器直接帮你复现前端 bug。这些能力拼在一起才让它从“玩具”变成“能接手真实项目”的工具。1.2 它解决了什么问题我在实际使用中体会最深的一点是它解决了“上下文断裂”的问题。过去我们用聊天式 AI 改代码经常要反复复制粘贴贴文件内容、贴报错信息、贴 git diff。opencode 这类终端 agent 不一样它直接跑在项目里文件系统、命令执行、环境变量都能接触到上下文是完整的。你只需要下指令它自己就能找到该死的 bug 在哪。它还解决了“多步任务”的落地问题。比如“帮我重构这个模块把 HTTP 请求逻辑抽出来”这种任务如果交给普通助手它会给你一段代码让你自己填opencode 则可能直接新建文件、改写引用、跑测试最后给你一个完整的 diff。这也是我在真实项目里更愿意用它处理大型重构的原因。1.3 适合谁用我觉得以下几类人用它的收益最大日常在终端里做开发、能接受命令行工作流的人。已经受够了手动把错误信息复制进网页的工程师。想用 AI 处理跨文件重构、批量改动、测试修复等复杂任务的人。对 IDE 内置插件不满意想要一个不依赖编辑器的独立 agent 的人。如果你完全不用命令行或者你只想让它“随便聊聊天”而不是干活那 opencode 大概率不适合你。它的主场就是项目目录不是聊天框。2. 安装 opencode从命令行到桌面版和 IDE 插件2.1 三种常见安装方式opencode 的安装方式没有统一标准不同版本和平台的差异还不小。我以自己验证过的三种方式为准方式一npm 全局安装。如果你本机有 Node.js 环境这是最简单的npm install -g opencode-ai opencode --version方式二官方安装脚本。适合 macOS 和 Linux也会自动处理 PATHcurl -fsSL https://opencode.ai/install | bash方式三Homebrew。这个适合 macOS 用户brew install opencode我个人的建议是先试 npm 方式如果网络环境允许装起来最快脚本方式适合想保持最新版本的人Homebrew 则适合本来就重度依赖 brew 管理工具的人。装完以后在任意项目目录下执行opencode就能进入交互界面。2.2 桌面版和 IDE 插件虽然本质上是终端工具但 opencode 生态里也有桌面版和 IDE 插件这一点被很多新手忽略。桌面版的作用是提供一个图形化界面专门给不习惯纯终端交互的人用。它一般包含项目列表、会话历史、模型切换面板底层调用的还是同一个命令行核心。简单说桌面版是“披着 GUI 壳的终端 agent”功能不会比命令行少太多但多窗口操作会舒服些。IDE 插件方面主要分两个阵营VS Code 插件和 JetBrains 系列插件。VS Code 里搜索 opencode 官方扩展装好以后可以直接在侧边栏开一个 opencode 面板选中代码右键发送给它让它解释或修改当前选区。JetBrains 系的 IntelliJ IDEA 插件也类似支持把当前文件路径、光标位置、选中内容一起传给 opencode甚至能在插件面板里直接查看它生成的 diff。我的个人习惯是日常小改动用 IDE 插件大重构和跨文件任务还是回到终端里跑因为终端里能看到完整输出信息密度更高。2.3 安装完先做的事装完别急着干活先把模型配置好。opencode 本身只是一个壳真正干活的还是底层的模型。你至少需要一个 API keyOpenAI 或 Anthropic 都行或者本地有一个能跑的模型比如 Ollama 拉下来的 Qwen Coder 系列。没配置模型就启动大概率只能看到欢迎界面发指令时直接报校验错误。注意第一次启动时opencode 通常会在用户目录生成配置文件一般在~/.config/opencode/下。先找到这个目录确认版本号和配置文件路径后面所有折腾都以这里为基准。一个非常反直觉的坑某些版本的 npm 包装完以后命令名不一定叫opencode有可能是opencode-ai或者需要npx opencode-ai才能启动。如果你敲opencode提示命令找不到先别急着怀疑安装失败用npm list -g --depth0查一下实际装的是哪个包名。3. 模型配置与接入怎么把各家大模型装进 opencode3.1 主流的 provider 配置方式opencode 的模型配置逻辑跟大多数终端 AI 工具类似通过环境变量设置 API key再用配置文件控制具体用哪个模型。以 OpenAI 为例export OPENAI_API_KEYsk-your-key然后启动 opencode在交互界面里输入/models或者按快捷键打开模型列表选择你要用的模型。Anthropic 的配置也差不多export ANTHROPIC_API_KEYsk-ant-your-key如果你的团队有统一的模型网关那么 opencode 也允许你通过配置文件自定义接口地址只需要把 base URL 指过去即可。当然我更建议普通用户先老老实实用官方 API 或本地模型避免折腾第三方接口带来的安全和稳定性问题。3.2 配置文件里到底能写什么opencode 的核心配置文件是opencode.json在 macOS 和 Linux 下通常位于~/.config/opencode/opencode.json。基本结构大概长这样{ $schema: https://opencode.ai/config.json, provider: { openai: { api_key: sk-xxx, model: gpt-4o }, anthropic: { api_key: sk-ant-xxx, model: claude-sonnet-4-20250514 }, ollama: { base_url: http://localhost:11434/v1, model: qwen2.5-coder:7b } } }注意新版本往往还支持在项目根目录放一个.opencode/config.json只对当前项目生效。这个机制特别适合团队协作可以把模型选择、忽略规则都放进仓库里让所有成员默认使用同一套配置。3.3 成本控制与模型选择的心得模型选型这件事我试过几轮之后总结出一个“大模型干大事小模型干小事”的原则。日常小问题、快速解释代码、写个简单脚本就用便宜的小模型比如 7B 级别的本地模型速度快而且烧不了几个 token跨文件重构、复杂测试修复、多层 bug 定位才动用旗舰大模型。opencode 里可以配置不同任务走不同模型吗我在用的版本里是可以通过会话内切换模型做到的。我会在开一个大型任务前手动切换到大模型任务收尾时切回小模型。你如果也这样做会发现每个月的 API 账单明显变低。另外一个省钱技巧告诉 opencode 忽略哪些目录。默认情况下它可能不会傻到把node_modules、target、.git都读一遍但保险起见你还是应该在配置里写上{ ignore: [ node_modules/**, target/**, .git/**, dist/** ] }这不仅是省钱更是保命。否则模型在分析仓库时很容易被上万个依赖文件带偏回答质量直线下降。4. 核心功能拆解Skills、Memory、Agent 和 Playwright4.1 Skills把团队规范变成可复用的指令Skills 是 opencode 里最值得花时间研究的机制。简单说它就是一个人为定义好的指令包你可以把“如何写提交信息”、“前端组件规范”、“数据库迁移流程”这类经验写成 markdown 文件放在指定目录下然后在对话中随时调用。以我的配置为例Skills 目录一般在~/.config/opencode/skills/下每个技能对应一个文件夹skills/ git-commit/ SKILL.md react-component/ SKILL.md bug-fix/ SKILL.mdSKILL.md 里不仅写“要做什么”更重要的是写“怎么做、边界在哪”。比如git-commit这个技能我会在文件里规定提交信息的格式、必须包含的内容、以及禁止把哪些文件提交进去。这样模型在生成 commit message 时就不会跑偏成“update code”这种毫无价值的信息。我的体会是Skills 的价值在于“沉淀”。个人用的时候可以把常用指令固化下来团队用的时候可以把代码规范灌进去。你不需要每次重复解释项目背景只要调用对应技能模型就能按团队套路干活。4.2 Memory让工具记住项目背景和你的习惯Memory 机制解决的是“跨会话记忆”问题。没有记忆时每次启动 opencode 都像换了一个新同事你得重新交代一遍项目架构。有了 Memory它会记住你之前给过它的背景信息并在后续会话中自动参考。Memory 一般存储在配置文件目录下的memory.md之类的文件里。它会记录几类信息项目的技术栈和目录结构。你常用的命令或工作流。已经解决过的问题和结论。你明确说过的偏好比如“别动测试文件”“注释用中文”“优先用现有工具函数”。我强烈建议你在项目开始前先花五分钟手动编辑一下 Memory 文件把项目背景写进去。这一步的收益比换更贵的模型还大。如果等项目已经乱成一团再让模型自己总结效果会大打折扣。4.3 Agent 模式从“问一句答一句”变成“自动跑完整条路”opencode 里最核心的交互模式就是 Agent。你在指令里给它一个目标它会把目标拆解成一系列步骤然后一步步执行。你不需要每一步都确认它可以自动读取文件、修改代码、运行命令。这种模式最适合“把活直接干了”的需求。我当时实际测试过一个场景让它修复一个 Java Maven 项目里的编译错误。我给它一条指令“看下最近的编译报错修复它并保证mvn test能过。”它会先执行mvn compile拿到报错然后定位到对应的.java文件修改代码再重新编译。整个过程我只需要盯着输出偶尔在它卡住时追加一句指引。最后它甚至自己跑了mvn test来验证结果。这里面有一个重要的使用技巧给你的 Agent 设定清晰的验收标准。不要只说“修 bug”要说“修复问题并让mvn test全绿”。有了验收标准模型才知道什么时候该停下来而不是改完就认为自己完成了。4.4 Playwright让 opencode 自己打开浏览器找前端 bug这个功能我特别想单独讲因为它是很多人没意识到的高价值能力。opencode 能调用 Playwright 驱动真实浏览器这意味着你可以让它复现一个前端 bug而不仅仅是读代码猜测。实际操作中我会在 opencode 会话里输入类似这样的指令帮我用 Playwright 复现这个 bug 访问 http://localhost:5173 点击“登录”按钮 输入任意邮箱和密码 观察控制台是否报错。 如果页面出现异常把截图和报错信息发给我。然后 opencode 会自动启动浏览器一步步执行操作把页面状态和 console 输出反馈回来。这个能力在面对“刷新才出现”“只在特定浏览器出现”的诡异 bug 时特别有用因为你可以让 AI 在真实环境里反复试而不是靠肉眼猜测。不过这里有个前提你得保证本地开发服务已经启动而且 opencode 有权限操作浏览器的调试端口。如果遇到 Playwright 连不上浏览器优先检查 Chrome DevTools 调试端口是否开启或者看 opencode 日志里的具体报错。5. 在真实项目里跑一次 opencode从接手到交付5.1 接手一个已有项目时的正确姿势接手一个没见过的项目是 opencode 最能发挥作用的场景之一。我通常的做法是先在项目根目录启动 opencode然后输入先给我一份这个项目的结构说明 - 技术栈是什么 - 入口文件在哪 - 如何本地启动 - 测试命令是什么它读完代码后会给出一个结构概览。如果信息不够我会追加“去读 README 和 package.json如果发现启动脚本尝试运行并告诉我结果。”这一步的关键是让 Agent 自己把项目跑起来否则后续改动无法验证。等模型对这个项目有了基本了解我会把 Memory 文件更新一版把技术栈、启动方式、测试命令、常见报错都写进去。这样一来后续会话就不用每次重新摸一遍项目了。5.2 从需求到实现的完整流程我拿一个实际需求举例子“给这个 Vue 项目新增一个用户列表页数据从现有 API 获取列表要有搜索和分页。”我会在 opencode 里输入需求新增一个用户列表页。 - 路由/users - 数据接口/api/users - 支持关键词搜索和分页 - 样式参考现有页面 请先列出你将修改的文件清单确认后再动手。注意我特意加了“确认后再动手”这句。因为复杂需求很容易让 Agent 陷入自由发挥确认文件清单能让我在它动手前把好关。这个习惯能避免很多灾难。等它列出清单并开始改代码后我会每隔一段时间看一次 diff。opencode 会在改动文件时展示 diff遇到我不同意的地方可以直接喊停让它撤销某个文件的改动。最后我一定会让它跑一遍测试或构建改完以后执行 npm run build如果有报错就修复。在真实项目里这一遍构建验证能挡住至少一半的“低级错误”。很多时候模型写出来的代码逻辑没问题但缺导入、少依赖、类型对不上只有跑构建才会暴露。6. 常见问题与排查实录6.1 “opencode 不是内部或外部命令”在 Windows PowerShell 里经常看到这个报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个问题的本质是命令没有被加到 PATH 环境变量里。npm 全局安装后可执行文件一般会放到 npm 的 global bin 目录但这个目录未必在系统 PATH 里。解决办法有两个一是用npx opencode-ai临时运行二是把 npm 全局 bin 目录加入 PATH。最稳的方式是找到 npm 全局 bin 路径npm prefix -g然后把输出的路径Windows 下一般是%APPDATA%\npm手动加到用户 PATH 中重开终端再试。macOS 和 Linux 上也常有类似问题。用安装脚本装完后如果提示找不到命令先检查一下~/.opencode/bin或/usr/local/bin是否在 PATH 里再执行source ~/.bashrc或source ~/.zshrc。6.2 “unexpected server error” 到底怎么查很多人启动 opencode 后发指令会收到这类报错error: unexpected server error. check server logs...这个报错太笼统了十有八九不是 opencode 本身的问题而是底层模型 API 请求失败。最常见的几个诱因API key 无效或配额超了。先确认环境变量是否真的设置成功echo $OPENAI_API_KEY看看。网络问题。如果你所在环境访问模型 API 不稳定请求大概率会中断。模型名称写得不对。配置文件里填了一个不存在或未开通的模型 ID服务端直接拒绝。排查顺序我建议是先直接 curl 一下模型 API确认接口能通再确认 opencode 配置里的 model ID 正确最后去看 opencode 日志一般在~/.local/share/opencode/log或临时目录下。如果日志里能看到 401那就是 key 的问题如果是 404那就是模型 ID 的问题。6.3 模型越改越乱怎么限制它的“自由发挥”这是使用 agent 类工具最常见的痛点。模型在自动模式下会越改越起劲甚至把你本来没打算动的文件也改了。我的解决方法是动手前明确指定“只允许修改哪几个文件”。明确告诉它哪些目录不允许触碰比如src/api下的文件不要改。动手后立刻检查 diff发现问题及时回滚。开启“计划模式”或“确认模式”让它在执行每一步前先告诉我要做什么。这也是我在对比不同 agent 工具时最看重的一点。一个 agent 能力强不强是一方面能不能被我控制住是更重要的方面。opencode 的交互设计在这方面做得还行但前提是你得主动设置好边界。6.4 在 IDE 插件里断连、同步不及时的问题如果你跟我一样同时用终端和 IDE 插件可能会发现 IDE 插件里的会话和终端里的会话不是同一个状态。这是因为它们各自独立维护了一个运行实例。为了避免混乱我一般只保留一个实例在跑比如在终端里做复杂任务时就不开 IDE 插件的会话否则模型对项目状态的理解会产生分歧。如果 IDE 插件连不上 opencode 后端大概率是本地端口被占用或版本不一致。先重启插件再检查 opencode 后台进程必要时直接把两个都退出从干净状态重新启动。这类问题通常不是配置错误而是进程状态脏了。7. 横向对比opencode、Codex CLI 和 Claude Code我知道很多人纠结“到底用哪个”。我自己三个都试过坦率说各有侧重点没有绝对的最优选。下面这张表是我基于当前版本的个人感受维度opencodeCodex CLIClaude Code出身开源社区项目模型无关OpenAI 官方出品Anthropic 官方出品模型支持范围广可接多厂商偏 OpenAI 生态偏 Claude 生态Skills 机制支持可自定义技能包较弱有类似机制浏览器自动化内置 Playwright有限支持有限支持配置灵活度高中等中等上手成本中等低低如果你是纯 OpenAI 生态用户Codex CLI 的优势是官方血统纯正API 兼容性最好。如果你重度使用 ClaudeClaude Code 的长上下文和对 Anthropic 模型的理解度会更顺。但如果你跟我一样不想被单一厂商绑定希望一个工具能切换 OpenAI、Anthropic 和本地模型opencode 的灵活性就体现出来了。还有一个容易被忽略的维度社区生态。opencode 的开源社区更新速度很快Skills 和插件的扩展都在持续增长。你可以在社区里直接找到别人整理好的技能包导入进来用省去自己从头写指令的功夫。当然从不明来源导入技能包有一定风险我建议先看内容再决定要不要用别看到“神器”“全自动”就盲目安装。8. 收尾我的一点真实体会如果你此前一直在用网页版 AI 聊天写代码第一次用 opencode 可能会有点不习惯会觉得它“管太多”“跑太快”。但一旦你把项目规则、Skills、Memory 这几样东西配置到位它真的能变成一个可以托付整段任务的帮手。我最近的实际节奏是开一个新任务先在 Memory 里补充背景然后给 opencode 一条带验收标准的指令让它自己改代码、跑测试、给我 diff。我做的更多是审核而不是手把手指导。这种方式最大的变化是我把大量“搬运信息”的时间省了下来把精力放在真正需要判断的地方。最后分享一个我认为价值最高的配置习惯永远维护好项目根目录的规则文件把你对代码风格、提交规范、测试要求、禁止改动目录的期望全部写清楚。这个文件比选哪个模型、装哪个插件都重要。模型再强没有规则约束也只会给你一个看似合理但乱糟糟的仓库模型一般但有清晰规则加持反而能稳定输出可用的代码。opencode 的价值说到底就是把这些“使用规则”的执行成本降到了最低。要是你现在还在犹豫要不要换工具我建议你别先纠结选 opencode 还是 Claude Code。挑一个晚上在一个玩具项目里把 opencode 完整跑一遍装好、配一个模型、写一条技能、让它自己按需求改一次代码。跑完这一遍你自然就知道它适不适合你的工作流了。
