2026/9/8 18:38:26
FEATURED · 精选文章 
去年底我把日常编码的很多重复工作迁移到了终端里用 opencode 配合大模型来跑。说实话一开始我只是想找个能替代 IDE 里各类 AI 插件的命令行工具结果 opencode 成了我现在处理接手老项目、批量改代码、跑一遍测试再修这类任务的首选。如果你也在找一款开源、模型自由、能真正在终端里干活的 AI coding agent那这篇文章应该能帮你少踩很多坑。我尽量不写成文档翻译。我会按照实际使用的顺序opencode 是什么、怎么装、怎么配模型、怎么用起来、遇到问题怎么排查最后再分享一点个人体会。每个环节我都会讲清楚背后的思路基本是按我实际做过的事来写你可以直接照着操作。1. opencode 到底是什么先把这个工具讲明白1.1 一个跑在终端里的 AI 编码代理而不是另一个 IDEopencode 是一个开源Open Source的 AI 编码代理Coding Agent它的定位不是给编辑器加个自动补全而是在终端里替你执行一系列编码任务。你可以把它理解为一个能读项目文件、能改代码、能执行命令、能跑测试的 AI 协作者。它不像 Cursor 那样把自己绑在编辑器上而是作为独立命令运行你在任何目录下执行它它就会进入一个交互式终端界面然后基于当前项目上下文跟你对话。我第一次用的时候最直观的感受是这东西更像命令行里的结对编程搭档而不是输入法的智能提示。你给它一个任务比如帮我查一下登录接口为什么返回 401它会自己去翻代码、定位路由、看鉴权逻辑然后把结论和修改建议给你。如果你确认它甚至可以直接改文件、跑测试整个过程都在终端里完成不需要切窗口。适合用 opencode 的人大概有三类第一类是本身就在终端里写代码的开发者用它不会打断工作流第二类是要经常接手别人项目的工程师靠它快速理解陌生代码库第三类是写脚本、做工具类小项目的人用它直接把想法落地。当然它也支持 VSCode、JetBrains 等 IDE 插件形式所以不是终端党的朋友也能用。1.2 它和 Claude Code、Codex、IDE 补全插件的本质区别现在市面上 AI 编程工具挺多的我把它们分成三类代码补全类比如早期 Copilot 的模式你写一半它帮你续写下一段。这类工具的优点是快、侵入小缺点是没有全局视野改个跨文件的逻辑经常帮倒忙。编辑器内 Agent 类比如 Cursor、Copilot Workspace 里的智能代理。它们能理解整个仓库但依赖特定编辑器生态。终端 Agent 类比如 Claude Code、Codex CLI、opencode。它们独立于编辑器重点是读仓库、做计划、执行命令、看结果这个完整循环。opencode 和 Claude Code、Codex 最大的区别在哪我自己的判断是三点模型无关、完全开源、可定制性强。Claude Code 默认绑定 Claude 模型Codex 默认绑定 OpenAI 系模型而 opencode 在设计上就是模型无关的。你可以用 Anthropic、OpenAI、Gemini也可以用本地 Ollama 跑的模型或者走任意 OpenAI 兼容接口。这个特性对我来说非常关键因为我不想被单一模型的 API 价格、限流和更新节奏绑死哪个模型好用、哪个便宜我随时可以换。另外 opencode 有 Skills技能和 Memory记忆机制可以给 Agent 定义一套遇到某类任务时的标准操作流程也可以让它跨会话记住一些约定。这个在后面我会重点展开。提醒一下opencode 和 Codex、Claude Code 都还在快速迭代命名、参数、配置字段都有可能变化。这篇文章里我用的是当前比较通用的用法如果你装的版本较新以--help和官方文档为准。2. 安装与第一个会话从零开始跑起来2.1 多种安装方式按你的环境选一个opencode 的安装方式很灵活最常见的三种方式一npm 全局安装如果你已经装了 Node.js 环境这是最省事的一条路npm install -g opencode-ai安装完成后执行opencode --version能输出版本号就说明装好了。方式二官方安装脚本如果你不想装 Node.js或者希望用系统级命令直接管理可以用官方脚本安装curl -fsSL https://opencode.ai/install | bashmacOS 用户也可以顺便用 Homebrewbrew install sst/tap/opencode不过我用得最多的还是 npm 方式因为升级方便直接npm update -g opencode-ai就完事了。方式三桌面版和 IDE 插件opencode 有桌面版Desktop也有 VSCode、JetBrains 全家桶的插件。桌面版实际上是把终端界面包了一层 GUI适合不习惯命令行的人。VSCode 插件装好之后可以直接在编辑器里打开一个 opencode 面板底层调用的还是同一个 CLI。我的建议是如果你是重度命令行用户优先用 CLI如果你的项目组都在用某款 IDE那装插件配合使用会更顺。团队协作时CLI 有个好处是每个人体验一致不受 IDE 配置影响。这里顺带解释一个比较多人遇到的坑在 Windows 上如果执行opencode命令时提示无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称大概率是 npm 全局包所在的 bin 目录没有加入系统 PATH 环境变量。这个问题我放在第 5 章排查实录里详细说这里先记住一个临时验证方法用npx opencode也能跑起来但正式使用建议把 PATH 配好。2.2 启动前准备好你的模型 API Keyopencode 本身不提供模型它负责的是调用哪个模型、怎么调用、怎么把代码任务拆解执行所以你得先有一个能用的大模型 API。目前主要几条路线Anthropic Claude 系列设置环境变量ANTHROPIC_API_KEYOpenAI 系列设置环境变量OPENAI_API_KEYGoogle Gemini走对应的 provider 配置本地模型通过 Ollama 把开源模型跑起来复用 OpenAI 兼容接口各种第三方聚合平台只要提供 OpenAI 兼容的 Base URL都可以接我第一次跑通用的是 OpenAI 兼容接口配置方式大致是export OPENAI_API_KEY你的key export OPENAI_BASE_URLhttps://你的接口地址/v1设置好之后直接在当前目录执行opencode进入交互界面后它会按配置文件里指定的模型发起会话。你可以先问一句帮我看看这个项目的结构如果它回答得有条理说明安装和模型接入都成功了。2.3 第一次会话做什么先让 Agent 活动一下手脚很多新手第一次打开 opencode会直接丢一句帮我把项目重构了这种任务太大太模糊Agent 大概率会卡住或给你一堆没用的方案。我建议第一次会话控制在三步以内第一步确认它能正确读取上下文。输入用一句话总结这个目录是干什么的看它的回答是否基于当前目录的文件结构。第二步给它一个具体的小任务。比如在 README.md 末尾加一段「快速开始」章节内容包括安装命令和运行命令。这个任务涉及读文件、改文件、格式化能完整走一遍读写链路。第三步让它执行一个命令。比如运行一下测试把失败的用例列表告诉我。这一步能验证它的命令执行和结果读取能力。三次都正常就说明你的 opencode 基本可用了。这时候再上正式任务效率会高很多。3. 配置与模型接入把 opencode 调成你的顺手形状3.1 配置文件怎么组织从全局到项目级opencode 的配置采用项目配置优先于全局配置的层级结构。简单说你可以用一个全局配置文件放个人偏好比如默认模型、常用关键词、隐私选项然后在每个项目里放一个项目级配置定义这个项目专属的模型、权限和环境变量。我个人习惯是全局配置文件只放默认模型和通用偏好项目级配置放这个项目的测试命令、构建命令、特殊说明等。这样做的好处是换机器或换项目时个人配置能跟着走项目配置又能随仓库分享给团队。具体字段方面不同版本差异较大常见的包括model指定默认模型provider指定模型供应商permissionAgent 执行命令时是否需要人工确认instructions / AGENTS.md给 Agent 的额外项目说明我强烈建议每个项目都维护一个 AGENTS.md 或者在配置里写明项目约定。给大家看一个我常用的小模板# 项目约定 - 包管理器使用 pnpm不要使用 npm/yarn - 测试框架使用 Vitest不要用 Jest - 代码风格遵循仓库内 .eslintrc 配置 - 新增接口必须补充对应单元测试 - 提交信息使用 Conventional Commits 格式Agent 每次进入项目都会读到这些约定相当于给新人发了一本员工手册非常管用。3.2 接入不同模型的完整思路付费 API 与本地模型路线先讲付费 API。Anthropic 的模型在做代码任务时表现通常很强如果你预算允许直接设ANTHROPIC_API_KEY然后在配置里把 model 指到对应的 Claude 型号。OpenAI 的 GPT 系列也用同样方式设OPENAI_API_KEY。再说说免费和低成本路线。社区里有人用各种免费模型或试用额度我想泼一盆冷水这类接口的稳定性、隐私边界、合规性都不太可控。你要是拿 opencode 处理一些非敏感的个人项目可以试试但如果是公司业务代码我建议别省这个钱用正规渠道的模型 API 或本地模型更稳妥。本地模型的路线其实很有吸引力。你只需要在机器上装 Ollama拉一个模型然后让 opencode 走 OpenAI 兼容接口连接本机服务。大概流程是ollama pull llama3.1 ollama run llama3.1然后配置一个 provider把 Base URL 指向http://localhost:11434/v1即可。我实测下来的感受是本地开源模型在处理理解项目结构、生成中等复杂度代码这些任务上已经能用和顶级商业模型有差距但不至于不可用。关键优势是隐私安全、无额外费用、离线可用适合不太敏感的脚本工具项目。这里要给一个很重要的建议不同任务用不同模型比一个模型打天下效率高得多。比如复杂的架构分析用 Claude 系简单脚本用便宜模型批量改名这种机械任务甚至可以交给本地小模型。opencode 支持的按会话切换 model和多 provider 配置正好能实现这个策略。3.3 配合 ccswitch 这类配置切换工具的常见操作ccswitch 这类工具说白了就是模型/供应商配置一键切换器。你可能有多个 API 账号、多个供应商的额度ccswitch 能帮你快速切换当前 shell 的环境变量让不同 AI 工具读到不同的配置。和 opencode 配合时的逻辑其实很直接opencode 读取的是环境变量和配置文件ccswitch 切换的是环境变量所以只要在同一个终端会话里先执行 ccswitch 的切换再启动 opencode它读到的就是新配置。实际操作中要注意opencode 如果已经在运行切了环境变量是不会热生效的需要退出重进。还有ccswitch 切换的往往是当前终端开新窗口后环境变量可能回到默认值所以我会在项目的配置说明里写上建议先切配置再开 opencode的提示避免团队里有人开新窗口后莫名其妙用了错误模型。如果你没有用 ccswitch直接在配置里维护多个 provider在 opencode 的模型选择界面里切换也是可以的。工具只是手段核心诉求只有一个快速、可靠地在不同模型之间切换。4. 上手实战用 opencode 快速进入一个新项目4.1 让 Agent 先读懂项目再动手接手老项目不慌接手老项目最怕的是什么是代码还没看就被业务方催着改需求。opencode 这时候能帮你做大量熟悉项目的工作。我的标准流程是三步。第一步让它读 README、package.json、目录结构输出一份项目速览包括技术栈、模块划分、启动方式。第二步针对你不理解的部分展开问比如订单模块的支付状态流转在哪几个文件里实现它会定位到具体文件和函数。第三步让它结合 AGENTS.md 里的约定把如果要改某个功能应该动哪些文件的依赖关系列出来。这一步做完你就可以从两眼一抹黑变成心里有张地图。以前我接手一个中型后端项目光摸清结构就要半天现在让 Agent 出一份精读报告我再针对重点文件抽查确认一小时内能进入写代码状态。这里有个关键点Agent 说得再自信你也得抽查。AI 读代码也会漏、也会编尤其是复杂的跨模块逻辑必须人工确认关键结论。我的原则是它负责找路我负责把关。4.2 Skills把团队规范和执行流程固化给 AISkills 是 opencode 里我很喜欢的一个功能它解决的核心问题是如何让 Agent 每次做同一类事情时都按同一套标准流程来。打个比方你做菜时有个菜谱里面有步骤、有火候、有注意事项。Skills 就是给 Agent 准备的菜谱。你可以为写接口测试建立一个 Skill里面写明先分析现有测试文件风格再按照该风格新建测试文件覆盖正常和异常分支最后运行对应测试命令确保全部通过。Skills 文件通常放在项目里的约定目录比如.opencode/skills/下每个 Skill 一个目录里面有说明文档和示例。实际使用中你和 Agent 对话提到相关任务时可以主动要求使用 xxx skill 来做它会参照对应文档执行。社区里已经有各种打包好的 Skills 集合比如有人整理过一整套写代码前的需求澄清流程前端组件开发规范Superpowers之类的技能包你可以导入后按需修改。我的建议是先自己写两三个覆盖日常工作量的 Skill跑顺了再去折腾别人整理的因为别人整理的流程可能不完全匹配你的项目语境。4.3 Memory跨会话记住关键信息别让它每次都失忆没有 Memory 的 Agent 有个问题每次新开会话它都像第一天上班的新人完全不记得上次聊了啥。你在上个会话里说不要动 public 目录下的文件下个会话它又去改了。opencode 的 Memory 机制就是用来解决这个问题的。一些项目偏好、用户习惯、禁用目录、常用命令都可以让它在记忆里长期保存。使用方式上一般是通过对话告诉它记住本项目的构建命令行是 pnpm build:prod这个方向的操作它会写入约定位置也可以手动编辑记忆文件。我个人定期会整理一次记忆内容把过时的删掉把新的关键约束加进去。还记得记忆不是越多越好。塞太多无效信息反而会干扰判断。我建议只记录真正影响代码行为的硬约束比如禁止修改 schema 目录部署脚本必须走 CI这种而不是记一些琐碎的偏好。4.4 用 opencode 配合 Playwright 验证前端 Bug 的一个思路前端 bug 的验证一直是 Agent 的弱项因为改完代码很难立刻看到效果。我的做法是把 opencode 和 Playwright 串起来形成一个闭环。具体思路是先让 opencode 读相关源码定位可能导致缺陷的逻辑然后让它基于定位结果生成/修改一段 Playwright 脚本脚本里包含复现路径和断言接着在终端里跑这段脚本看实际输出与预期是否一致如果失败把失败信息抛回给 Agent让它继续分析修复修完再跑一遍回归。整个流程的提示语可以是请先查看 pages/login.tsx 和 api/auth.ts 的登录逻辑然后写一个 Playwright 脚本覆盖用户名或密码错误时页面应提示错误信息的场景。脚本写完后运行根据失败结果修复代码直到脚本通过。这样做的好处是把修改代码和验证效果连接起来了。对前端项目来说这比单纯让 Agent 写代码后断言看起来没问题要可靠得多。核心还是那句AI 负责效率和检索你负责定义怎样才算修好。5. 常见问题与排查技巧实录5.1 问题速查表这一节把我在实际使用中遇到的高频问题整理成一张表方便你直接查。报错 / 现象可能原因解决办法无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称npm 全局包的 bin 目录未加入 PATH检查 npm prefix把 bin 目录加入系统 PATH临时可用npx opencodeerror: unexpected server error. check server logs模型接口服务异常、网络问题或 provider 配置错误查看日志定位先切到最简单模型测试检查 API Key 和 Base URL429 / quota exceeded / rate limitAPI 额度不足或触发限流更换账号/模型等待窗口检查是否误用了免费/试用接口中文路径下运行异常、路径识别错误终端编码或工具对中文路径支持不佳项目路径尽量使用英文配置文件中路径统一用相对路径Permission denied / 权限确认弹窗频繁Agent 执行命令的权限策略过严在配置中为低风险命令设置自动执行高风险命令保持人工确认IDE 插件连不上 CLI / 提示找不到 opencode插件找不到环境变量里的 PATH 或 CLI 路径在 IDE 设置中显式指定 opencode 路径或先确认终端里可用模型回答明显变傻/失忆配置里模型被切换Memory 未生效检查当前 model确认 Memory 文件是否正确写入重启会话5.2 排查问题的三个通用招第一招看日志。opencode 的命令行工具一般都带日志能力启动时指定日志级别或者查看它放在缓存目录里的日志文件。当你看到 unexpected server error. check server logs 这类模棱两可的错误时日志基本能告诉你卡在哪一步是模型接口超时还是解析响应失败。第二招最小化复现。如果某个项目里行为怪异不要一直在项目里折腾。新建一个空目录放一个最小的测试文件看问题是否还存在。问题不在了就是项目里的某些配置或文件结构导致的问题还在就是工具或模型本身的问题。这个方法能帮你把项目问题和工具问题快速区分开。第三招版本回退或升级。opencode 迭代很快新版本引入 bug 也不罕见。如果某个功能之前好好的升级后坏了可以降级到上一版本试试。反之如果遇到奇怪的报错先升到最新版再查往往已经修了。5.3 两条容易忽略的细节一是环境变量的作用域。很多人把 API Key 写在 shell 配置文件里然后发现新开的终端有时能用有时不能用其实是不同的 shell 加载了不同的配置文件。我建议把 API Key 放在当前用户目录的配置文件中统一管理而不是散落在各个项目里。二是项目的配置文件是否被 Git 跟踪。项目级 opencode 配置文件里如果包含 API Key 或内网地址提交到仓库就是重大事故。我习惯在配置文件里只写 provider 名称和模型名敏感信息一律从环境变量读取同时把含密钥的可能文件加进 .gitignore。6. 我的几点个人体会用 opencode 小半年我最大的体会是工具的上限取决于你定义任务的能力。它能把查代码、改文件、跑测试这个循环跑得飞快但前提是你得给定清晰的边界和验收标准。如果你给的是把这个项目优化一下这种指令再强的模型也只会回复一堆空洞的建议。另外一个很深的感受是模型投入值得优于工具折腾。opencode 本身是免费的但底层模型的质量直接决定任务完成度。我最初为了省钱用较弱的模型结果改代码频繁返工时间和情绪成本都浪费了。后来换成更合适的模型效率反而翻倍。如果预算有限我建议优先保证模型质量工具层面保持简单。最后分享一个小技巧在配置里把低风险命令比如pnpm test、git diff、ls设为自动执行把高风险命令比如删除文件、推送远程、生产环境操作设为必须人工确认。这样一来Agent 跑测试、查状态时不用频繁打断你真正有风险的动作又会被卡一道闸。这个小配置比任何提示词都管用。
opencode 完全指南：终端里的 AI 编码代理实战
去年底我把日常编码的很多重复工作迁移到了终端里用 opencode 配合大模型来跑。说实话一开始我只是想找个能替代 IDE 里各类 AI 插件的命令行工具结果 opencode 成了我现在处理接手老项目、批量改代码、跑一遍测试再修这类任务的首选。如果你也在找一款开源、模型自由、能真正在终端里干活的 AI coding agent那这篇文章应该能帮你少踩很多坑。我尽量不写成文档翻译。我会按照实际使用的顺序opencode 是什么、怎么装、怎么配模型、怎么用起来、遇到问题怎么排查最后再分享一点个人体会。每个环节我都会讲清楚背后的思路基本是按我实际做过的事来写你可以直接照着操作。1. opencode 到底是什么先把这个工具讲明白1.1 一个跑在终端里的 AI 编码代理而不是另一个 IDEopencode 是一个开源Open Source的 AI 编码代理Coding Agent它的定位不是给编辑器加个自动补全而是在终端里替你执行一系列编码任务。你可以把它理解为一个能读项目文件、能改代码、能执行命令、能跑测试的 AI 协作者。它不像 Cursor 那样把自己绑在编辑器上而是作为独立命令运行你在任何目录下执行它它就会进入一个交互式终端界面然后基于当前项目上下文跟你对话。我第一次用的时候最直观的感受是这东西更像命令行里的结对编程搭档而不是输入法的智能提示。你给它一个任务比如帮我查一下登录接口为什么返回 401它会自己去翻代码、定位路由、看鉴权逻辑然后把结论和修改建议给你。如果你确认它甚至可以直接改文件、跑测试整个过程都在终端里完成不需要切窗口。适合用 opencode 的人大概有三类第一类是本身就在终端里写代码的开发者用它不会打断工作流第二类是要经常接手别人项目的工程师靠它快速理解陌生代码库第三类是写脚本、做工具类小项目的人用它直接把想法落地。当然它也支持 VSCode、JetBrains 等 IDE 插件形式所以不是终端党的朋友也能用。1.2 它和 Claude Code、Codex、IDE 补全插件的本质区别现在市面上 AI 编程工具挺多的我把它们分成三类代码补全类比如早期 Copilot 的模式你写一半它帮你续写下一段。这类工具的优点是快、侵入小缺点是没有全局视野改个跨文件的逻辑经常帮倒忙。编辑器内 Agent 类比如 Cursor、Copilot Workspace 里的智能代理。它们能理解整个仓库但依赖特定编辑器生态。终端 Agent 类比如 Claude Code、Codex CLI、opencode。它们独立于编辑器重点是读仓库、做计划、执行命令、看结果这个完整循环。opencode 和 Claude Code、Codex 最大的区别在哪我自己的判断是三点模型无关、完全开源、可定制性强。Claude Code 默认绑定 Claude 模型Codex 默认绑定 OpenAI 系模型而 opencode 在设计上就是模型无关的。你可以用 Anthropic、OpenAI、Gemini也可以用本地 Ollama 跑的模型或者走任意 OpenAI 兼容接口。这个特性对我来说非常关键因为我不想被单一模型的 API 价格、限流和更新节奏绑死哪个模型好用、哪个便宜我随时可以换。另外 opencode 有 Skills技能和 Memory记忆机制可以给 Agent 定义一套遇到某类任务时的标准操作流程也可以让它跨会话记住一些约定。这个在后面我会重点展开。提醒一下opencode 和 Codex、Claude Code 都还在快速迭代命名、参数、配置字段都有可能变化。这篇文章里我用的是当前比较通用的用法如果你装的版本较新以--help和官方文档为准。2. 安装与第一个会话从零开始跑起来2.1 多种安装方式按你的环境选一个opencode 的安装方式很灵活最常见的三种方式一npm 全局安装如果你已经装了 Node.js 环境这是最省事的一条路npm install -g opencode-ai安装完成后执行opencode --version能输出版本号就说明装好了。方式二官方安装脚本如果你不想装 Node.js或者希望用系统级命令直接管理可以用官方脚本安装curl -fsSL https://opencode.ai/install | bashmacOS 用户也可以顺便用 Homebrewbrew install sst/tap/opencode不过我用得最多的还是 npm 方式因为升级方便直接npm update -g opencode-ai就完事了。方式三桌面版和 IDE 插件opencode 有桌面版Desktop也有 VSCode、JetBrains 全家桶的插件。桌面版实际上是把终端界面包了一层 GUI适合不习惯命令行的人。VSCode 插件装好之后可以直接在编辑器里打开一个 opencode 面板底层调用的还是同一个 CLI。我的建议是如果你是重度命令行用户优先用 CLI如果你的项目组都在用某款 IDE那装插件配合使用会更顺。团队协作时CLI 有个好处是每个人体验一致不受 IDE 配置影响。这里顺带解释一个比较多人遇到的坑在 Windows 上如果执行opencode命令时提示无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称大概率是 npm 全局包所在的 bin 目录没有加入系统 PATH 环境变量。这个问题我放在第 5 章排查实录里详细说这里先记住一个临时验证方法用npx opencode也能跑起来但正式使用建议把 PATH 配好。2.2 启动前准备好你的模型 API Keyopencode 本身不提供模型它负责的是调用哪个模型、怎么调用、怎么把代码任务拆解执行所以你得先有一个能用的大模型 API。目前主要几条路线Anthropic Claude 系列设置环境变量ANTHROPIC_API_KEYOpenAI 系列设置环境变量OPENAI_API_KEYGoogle Gemini走对应的 provider 配置本地模型通过 Ollama 把开源模型跑起来复用 OpenAI 兼容接口各种第三方聚合平台只要提供 OpenAI 兼容的 Base URL都可以接我第一次跑通用的是 OpenAI 兼容接口配置方式大致是export OPENAI_API_KEY你的key export OPENAI_BASE_URLhttps://你的接口地址/v1设置好之后直接在当前目录执行opencode进入交互界面后它会按配置文件里指定的模型发起会话。你可以先问一句帮我看看这个项目的结构如果它回答得有条理说明安装和模型接入都成功了。2.3 第一次会话做什么先让 Agent 活动一下手脚很多新手第一次打开 opencode会直接丢一句帮我把项目重构了这种任务太大太模糊Agent 大概率会卡住或给你一堆没用的方案。我建议第一次会话控制在三步以内第一步确认它能正确读取上下文。输入用一句话总结这个目录是干什么的看它的回答是否基于当前目录的文件结构。第二步给它一个具体的小任务。比如在 README.md 末尾加一段「快速开始」章节内容包括安装命令和运行命令。这个任务涉及读文件、改文件、格式化能完整走一遍读写链路。第三步让它执行一个命令。比如运行一下测试把失败的用例列表告诉我。这一步能验证它的命令执行和结果读取能力。三次都正常就说明你的 opencode 基本可用了。这时候再上正式任务效率会高很多。3. 配置与模型接入把 opencode 调成你的顺手形状3.1 配置文件怎么组织从全局到项目级opencode 的配置采用项目配置优先于全局配置的层级结构。简单说你可以用一个全局配置文件放个人偏好比如默认模型、常用关键词、隐私选项然后在每个项目里放一个项目级配置定义这个项目专属的模型、权限和环境变量。我个人习惯是全局配置文件只放默认模型和通用偏好项目级配置放这个项目的测试命令、构建命令、特殊说明等。这样做的好处是换机器或换项目时个人配置能跟着走项目配置又能随仓库分享给团队。具体字段方面不同版本差异较大常见的包括model指定默认模型provider指定模型供应商permissionAgent 执行命令时是否需要人工确认instructions / AGENTS.md给 Agent 的额外项目说明我强烈建议每个项目都维护一个 AGENTS.md 或者在配置里写明项目约定。给大家看一个我常用的小模板# 项目约定 - 包管理器使用 pnpm不要使用 npm/yarn - 测试框架使用 Vitest不要用 Jest - 代码风格遵循仓库内 .eslintrc 配置 - 新增接口必须补充对应单元测试 - 提交信息使用 Conventional Commits 格式Agent 每次进入项目都会读到这些约定相当于给新人发了一本员工手册非常管用。3.2 接入不同模型的完整思路付费 API 与本地模型路线先讲付费 API。Anthropic 的模型在做代码任务时表现通常很强如果你预算允许直接设ANTHROPIC_API_KEY然后在配置里把 model 指到对应的 Claude 型号。OpenAI 的 GPT 系列也用同样方式设OPENAI_API_KEY。再说说免费和低成本路线。社区里有人用各种免费模型或试用额度我想泼一盆冷水这类接口的稳定性、隐私边界、合规性都不太可控。你要是拿 opencode 处理一些非敏感的个人项目可以试试但如果是公司业务代码我建议别省这个钱用正规渠道的模型 API 或本地模型更稳妥。本地模型的路线其实很有吸引力。你只需要在机器上装 Ollama拉一个模型然后让 opencode 走 OpenAI 兼容接口连接本机服务。大概流程是ollama pull llama3.1 ollama run llama3.1然后配置一个 provider把 Base URL 指向http://localhost:11434/v1即可。我实测下来的感受是本地开源模型在处理理解项目结构、生成中等复杂度代码这些任务上已经能用和顶级商业模型有差距但不至于不可用。关键优势是隐私安全、无额外费用、离线可用适合不太敏感的脚本工具项目。这里要给一个很重要的建议不同任务用不同模型比一个模型打天下效率高得多。比如复杂的架构分析用 Claude 系简单脚本用便宜模型批量改名这种机械任务甚至可以交给本地小模型。opencode 支持的按会话切换 model和多 provider 配置正好能实现这个策略。3.3 配合 ccswitch 这类配置切换工具的常见操作ccswitch 这类工具说白了就是模型/供应商配置一键切换器。你可能有多个 API 账号、多个供应商的额度ccswitch 能帮你快速切换当前 shell 的环境变量让不同 AI 工具读到不同的配置。和 opencode 配合时的逻辑其实很直接opencode 读取的是环境变量和配置文件ccswitch 切换的是环境变量所以只要在同一个终端会话里先执行 ccswitch 的切换再启动 opencode它读到的就是新配置。实际操作中要注意opencode 如果已经在运行切了环境变量是不会热生效的需要退出重进。还有ccswitch 切换的往往是当前终端开新窗口后环境变量可能回到默认值所以我会在项目的配置说明里写上建议先切配置再开 opencode的提示避免团队里有人开新窗口后莫名其妙用了错误模型。如果你没有用 ccswitch直接在配置里维护多个 provider在 opencode 的模型选择界面里切换也是可以的。工具只是手段核心诉求只有一个快速、可靠地在不同模型之间切换。4. 上手实战用 opencode 快速进入一个新项目4.1 让 Agent 先读懂项目再动手接手老项目不慌接手老项目最怕的是什么是代码还没看就被业务方催着改需求。opencode 这时候能帮你做大量熟悉项目的工作。我的标准流程是三步。第一步让它读 README、package.json、目录结构输出一份项目速览包括技术栈、模块划分、启动方式。第二步针对你不理解的部分展开问比如订单模块的支付状态流转在哪几个文件里实现它会定位到具体文件和函数。第三步让它结合 AGENTS.md 里的约定把如果要改某个功能应该动哪些文件的依赖关系列出来。这一步做完你就可以从两眼一抹黑变成心里有张地图。以前我接手一个中型后端项目光摸清结构就要半天现在让 Agent 出一份精读报告我再针对重点文件抽查确认一小时内能进入写代码状态。这里有个关键点Agent 说得再自信你也得抽查。AI 读代码也会漏、也会编尤其是复杂的跨模块逻辑必须人工确认关键结论。我的原则是它负责找路我负责把关。4.2 Skills把团队规范和执行流程固化给 AISkills 是 opencode 里我很喜欢的一个功能它解决的核心问题是如何让 Agent 每次做同一类事情时都按同一套标准流程来。打个比方你做菜时有个菜谱里面有步骤、有火候、有注意事项。Skills 就是给 Agent 准备的菜谱。你可以为写接口测试建立一个 Skill里面写明先分析现有测试文件风格再按照该风格新建测试文件覆盖正常和异常分支最后运行对应测试命令确保全部通过。Skills 文件通常放在项目里的约定目录比如.opencode/skills/下每个 Skill 一个目录里面有说明文档和示例。实际使用中你和 Agent 对话提到相关任务时可以主动要求使用 xxx skill 来做它会参照对应文档执行。社区里已经有各种打包好的 Skills 集合比如有人整理过一整套写代码前的需求澄清流程前端组件开发规范Superpowers之类的技能包你可以导入后按需修改。我的建议是先自己写两三个覆盖日常工作量的 Skill跑顺了再去折腾别人整理的因为别人整理的流程可能不完全匹配你的项目语境。4.3 Memory跨会话记住关键信息别让它每次都失忆没有 Memory 的 Agent 有个问题每次新开会话它都像第一天上班的新人完全不记得上次聊了啥。你在上个会话里说不要动 public 目录下的文件下个会话它又去改了。opencode 的 Memory 机制就是用来解决这个问题的。一些项目偏好、用户习惯、禁用目录、常用命令都可以让它在记忆里长期保存。使用方式上一般是通过对话告诉它记住本项目的构建命令行是 pnpm build:prod这个方向的操作它会写入约定位置也可以手动编辑记忆文件。我个人定期会整理一次记忆内容把过时的删掉把新的关键约束加进去。还记得记忆不是越多越好。塞太多无效信息反而会干扰判断。我建议只记录真正影响代码行为的硬约束比如禁止修改 schema 目录部署脚本必须走 CI这种而不是记一些琐碎的偏好。4.4 用 opencode 配合 Playwright 验证前端 Bug 的一个思路前端 bug 的验证一直是 Agent 的弱项因为改完代码很难立刻看到效果。我的做法是把 opencode 和 Playwright 串起来形成一个闭环。具体思路是先让 opencode 读相关源码定位可能导致缺陷的逻辑然后让它基于定位结果生成/修改一段 Playwright 脚本脚本里包含复现路径和断言接着在终端里跑这段脚本看实际输出与预期是否一致如果失败把失败信息抛回给 Agent让它继续分析修复修完再跑一遍回归。整个流程的提示语可以是请先查看 pages/login.tsx 和 api/auth.ts 的登录逻辑然后写一个 Playwright 脚本覆盖用户名或密码错误时页面应提示错误信息的场景。脚本写完后运行根据失败结果修复代码直到脚本通过。这样做的好处是把修改代码和验证效果连接起来了。对前端项目来说这比单纯让 Agent 写代码后断言看起来没问题要可靠得多。核心还是那句AI 负责效率和检索你负责定义怎样才算修好。5. 常见问题与排查技巧实录5.1 问题速查表这一节把我在实际使用中遇到的高频问题整理成一张表方便你直接查。报错 / 现象可能原因解决办法无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称npm 全局包的 bin 目录未加入 PATH检查 npm prefix把 bin 目录加入系统 PATH临时可用npx opencodeerror: unexpected server error. check server logs模型接口服务异常、网络问题或 provider 配置错误查看日志定位先切到最简单模型测试检查 API Key 和 Base URL429 / quota exceeded / rate limitAPI 额度不足或触发限流更换账号/模型等待窗口检查是否误用了免费/试用接口中文路径下运行异常、路径识别错误终端编码或工具对中文路径支持不佳项目路径尽量使用英文配置文件中路径统一用相对路径Permission denied / 权限确认弹窗频繁Agent 执行命令的权限策略过严在配置中为低风险命令设置自动执行高风险命令保持人工确认IDE 插件连不上 CLI / 提示找不到 opencode插件找不到环境变量里的 PATH 或 CLI 路径在 IDE 设置中显式指定 opencode 路径或先确认终端里可用模型回答明显变傻/失忆配置里模型被切换Memory 未生效检查当前 model确认 Memory 文件是否正确写入重启会话5.2 排查问题的三个通用招第一招看日志。opencode 的命令行工具一般都带日志能力启动时指定日志级别或者查看它放在缓存目录里的日志文件。当你看到 unexpected server error. check server logs 这类模棱两可的错误时日志基本能告诉你卡在哪一步是模型接口超时还是解析响应失败。第二招最小化复现。如果某个项目里行为怪异不要一直在项目里折腾。新建一个空目录放一个最小的测试文件看问题是否还存在。问题不在了就是项目里的某些配置或文件结构导致的问题还在就是工具或模型本身的问题。这个方法能帮你把项目问题和工具问题快速区分开。第三招版本回退或升级。opencode 迭代很快新版本引入 bug 也不罕见。如果某个功能之前好好的升级后坏了可以降级到上一版本试试。反之如果遇到奇怪的报错先升到最新版再查往往已经修了。5.3 两条容易忽略的细节一是环境变量的作用域。很多人把 API Key 写在 shell 配置文件里然后发现新开的终端有时能用有时不能用其实是不同的 shell 加载了不同的配置文件。我建议把 API Key 放在当前用户目录的配置文件中统一管理而不是散落在各个项目里。二是项目的配置文件是否被 Git 跟踪。项目级 opencode 配置文件里如果包含 API Key 或内网地址提交到仓库就是重大事故。我习惯在配置文件里只写 provider 名称和模型名敏感信息一律从环境变量读取同时把含密钥的可能文件加进 .gitignore。6. 我的几点个人体会用 opencode 小半年我最大的体会是工具的上限取决于你定义任务的能力。它能把查代码、改文件、跑测试这个循环跑得飞快但前提是你得给定清晰的边界和验收标准。如果你给的是把这个项目优化一下这种指令再强的模型也只会回复一堆空洞的建议。另外一个很深的感受是模型投入值得优于工具折腾。opencode 本身是免费的但底层模型的质量直接决定任务完成度。我最初为了省钱用较弱的模型结果改代码频繁返工时间和情绪成本都浪费了。后来换成更合适的模型效率反而翻倍。如果预算有限我建议优先保证模型质量工具层面保持简单。最后分享一个小技巧在配置里把低风险命令比如pnpm test、git diff、ls设为自动执行把高风险命令比如删除文件、推送远程、生产环境操作设为必须人工确认。这样一来Agent 跑测试、查状态时不用频繁打断你真正有风险的动作又会被卡一道闸。这个小配置比任何提示词都管用。 
