opencode 完整指南：终端开源编码代理的安装、配置与实战

如果你也和我一样，每天有三分之一的时间耗在“复制报错 → 切窗口 → 问 AI → 切回来 → 把补丁粘进去”的循环里，那 opencode 值得你认真试一下。它不是又一个聊天机器人套壳，而是一个跑在终端里的开源编码代理，跟它说“把这几个模块的重构做了”，它就能自己读代码、改文件、跑测试，然后把 diff 留给你审。下面这些经验是我高强度用了两三个月之后的完整记录，从安装、配置、日常玩法到报错排查都有，适合想从图形界面 AI 助手切换到终端工作流的开发者。

我会尽量把每个环节讲透，包括那些文档里很少写、但实际操作一定会踩的细节。先说结论：opencode 目前已经可以用来正经干活了，但前提是你要理解它的定位、配置清楚模型，并且养成“改完必审 diff”的习惯。这三点做好了，它在你手里的生产力会远超 Cursor 那种图形工具；做不好，你只会觉得它是个更卡顿的聊天窗口。

1. 先搞清楚 opencode 到底解决什么问题

1.1 日常开发里最浪费时间的一个动作

先说一个场景。你正在 IDE 里写接口，报错信息一大串，于是你复制、切到浏览器里的 AI 工具、粘贴、等回复、再复制补丁、切回来、修改文件、跑测试。如果跑挂了，再重复一轮。这个过程表面上看每趟也就一两分钟，但一天下来几十次切换，注意力早就碎成渣了。

opencode 的处理方式是把代理直接放进你的项目目录。它能看到你的代码、能执行终端命令、能搜索文件、能修改代码，你只需要在最下面一行输入指令，它自己完成“读代码 → 思考 → 改文件 → 执行验证”这一串动作。效率提升的关键不是它比别的模型更聪明，而是它不用你手动搬运上下文。

另一个痛点是上下文连续。浏览器里的对话每次都要重新解释项目背景，而 opencode 启动时就带着当前目录的语境，还能配合项目说明文件自动加载约定。这两个特性叠加起来，才是它作为终端代理的核心价值。

1.2 opencode 和 Codex CLI、Claude Code 的区别

先说明我的立场：我不是说其他工具不好，而是在“开源、模型无关、可配置”这三点上，opencode 更对我的胃口。Codex CLI 绑定了 OpenAI 的模型栈，Claude Code 对 Anthropic 系列模型体验最好，Cursor 则是一个完整的 IDE 封闭生态。opencode 是反着来的，它把自己定位成一个开放式调度器，各种模型都能接。

对普通开发者来说，最实际的影响是：你用 opencode 就不需要因为换模型而换工具。今天用本地跑开源模型省成本，明天接到某个云服务商的 API，只改配置文件就行，操作习惯完全不变。而且它整个项目都是开放的，出问题可以自己修，社区提 issue 也回复得快。

另外提一句，网上有人问“opencode是哪家公司的”，严格说它不属于哪一家商业公司，核心代码在 GitHub 上由社区共同维护。这一点很重要——你不用担心某个厂商突然调整策略导致工具不可用。

1.3 谁适合用 opencode，谁可以先观望

我会说，适合用 opencode 的人是这几类：平时主力工作流就是终端 + git 的开发者；经常要跨项目维护、需要快速读懂陌生代码的人；以及重度使用 AI 编程但受够了每次重复贴上下文的用户。还有一类是喜欢折腾配置的，opencode 的 provider、Skills、记忆机制都有足够的可玩性。

不太适合的则是这几类：完全不想碰命令行的纯视觉用户；团队协作中要求所有人统一 IDE 插件、不接受终端操作规范的环境；以及特别简单的脚本任务，比如只写个几十行的临时脚本，图形工具可能反而更快。我个人的判断是，工具没有高低，只有匹配不匹配，opencode 适合的是“把 AI 当结对程序员”的人，而不是“把 AI 当自动补全”的人。

2. 安装 opencode：三条路怎么选

2.1 三种安装方式

安装 opencode 没有太多玄学，但不同平台确实有细微差别。我推荐优先用 npm 安装，因为升级最方便，一条命令就能搞定。前提是你机器上已经有 Node.js 环境，建议版本在 20 以上，太老的版本会遇到依赖兼容问题。

npm install -g opencode-ai opencode --version

如果你还没有 Node.js，或者不想为了一个工具单独装运行时，可以走官方安装脚本。脚本会把可执行文件放到系统路径下，省去手动配置环境变量。macOS 用户也可以先看看本机包管理器是否已经收录，用 brew 这类工具装的好处是卸载干净，但包版本可能不是最新的。

Windows 用户要注意一个坑：npm 全局安装完之后，如果终端提示“opencode 不是内部或外部命令”，基本就是 npm 的全局 bin 目录没在 PATH 里。后面第 6 节我会专门写排查方法，这里先记着有这回事。

2.2 启动 opencode 后你会看到什么

安装完成，进到你的项目目录，输入opencode回车，会进入一个全屏的 TUI 界面。第一次看到它的人大多会有两个反应：一是“这界面怎么这么简洁”，二是“接下来按什么”。

底部是输入框，你直接打字就是跟代理对话；顶部是当前模型和会话信息；右侧通常会有模型列表和可用工具列表；按Ctrl+K能打开命令面板，输入/可以看到斜杠命令。界面虽然简单，但信息密度很高，比网页聊天窗能放下的内容多得多。

这里要提醒一句：请务必在 Windows Terminal、iTerm2、kitty 这类现代终端里运行，别用老旧的 cmd 窗口或者不更新多年的终端模拟器。opencode 的界面依赖较新的终端特性，终端太老会出现渲染错位、按键无响应、显示方块字之类的怪问题。

2.3 别急着对话，先配好模型

很多新手装完 opencode，第一件事就是敲一句话让它写代码，然后发现它半天不回应，或者直接报错。原因通常是模型根本没配置好。opencode 本身不带模型，它只是调度器，你得告诉它用哪个模型、去哪连、用什么密钥。

所以在聊安装的时候我必须把“配模型”提上来。最简单的方式是启动 opencode 后输入/models，它会引导你选择 provider 并填写 API Key；你也可以手工编辑配置文件，下一节我会给出完整的配置示例。先把这个做完，再开始玩那些花活。

3. 模型配置：让 opencode 真正开始干活

3.1 配置文件与全局/项目级作用域

opencode 的配置支持全局和项目两级。全局配置放在用户目录下的~/.config/opencode/opencode.json（Windows 上对应%USERPROFILE%\.config\opencode\opencode.json），项目配置放在项目根目录的opencode.json或opencode.jsonc。

两级的优先级是项目配置覆盖全局配置。我自己的习惯是：全局配置里放通用的模型和密钥，项目配置里放这个项目特有的规则和模型偏好。这样换项目时不用改全局，也避免把某个项目的特殊配置带到别的项目里去。

配置文件的格式是标准的 JSON。如果你用的版本支持 JSONC，那就能写注释，强烈建议开启，因为 provider 一多，没注释的配置文件读起来很痛苦。

3.2 一次性配好本地模型和云端模型

先说本地模型。最省心的组合是 opencode + Ollama，你在本地把 Ollama 装好，拉一个适合写代码的开源模型，然后在 opencode 配置里指定它。这样跑起来不花钱，数据也不出本机，适合日常小任务和隐私敏感的场景。

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "name": "Ollama", "options": { "baseURL": "http://localhost:11434" }, "models": { "qwen2.5-coder:14b": { "name": "Qwen 2.5 Coder 14B" } } } }, "model": "ollama/qwen2.5-coder:14b" }

注意看这里的结构：provider 里定义连接地址和模型清单，model 字段指定默认用哪个。如果你本地 Ollama 拉的是别的模型，把名字改掉就行。

云端模型要复杂一点，因为不同服务商的接入方式不完全一样。以国内能正常注册使用的服务为例，你只需要申请 API Key，然后把服务商地址和凭据填到配置里。opencode 的 provider 配置基本都遵循“模型 SDK + baseURL + apiKey”这套模式。

{ "provider": { "deepseek": { "npm": "@ai-sdk/deepseek", "name": "DeepSeek", "options": { "baseURL": "https://api.deepseek.com", "apiKey": "sk-你的密钥" }, "models": { "deepseek-chat": { "name": "DeepSeek V3" } } } }, "model": "deepseek/deepseek-chat" }

很多服务商其实已经被 opencode 内置支持，你不需要填 npm 字段，直接选 provider 填 key 就行。需要自定义的时候才用上面的写法。如果你用的模型服务商列表里没有，也可以找支持“OpenAI 兼容接口”的服务，只要地址、密钥、模型名三个参数正确，大部分都能跑起来。

关于“免费模型”，我的观点是不要迷信免费这东西，关键看稳定性和能力。opencode 本身不生产模型，真正的免费来源无非两个：一是本地跑开源模型，成本为零但吃你机器性能；二是云服务商提供的免费试用额度或限时免费模型，适合尝鲜评估。真正常态化使用时，花点小钱换来的稳定输出体验，远超一直折腾免费入口的时间成本。

3.3 项目级约定：AGENTS.md 和 /init

配好模型后，还有一个动作强烈建议每次新建项目都做：在 opencode 里执行/init。这个命令会让它扫描当前项目的技术栈、目录结构、构建方式和已有规范，然后自动生成一个项目说明文件。

这个说明文件的作用是“给代理建立项目心智”。下次新开会话时，opencode 会读取它，自动知道这个项目用什么语言、怎么跑测试、目录怎么组织。看起来不起眼，实际效果差别巨大：没有它，代理经常要花很多轮对话去猜项目结构；有了它，第一轮对话就能直接干活。

我个人的做法是在项目根目录额外维护一份 AGENTS.md，手写补充一些不会自动生成的约定，比如“接口返回体统一用 { code, data, message } 结构”“提交信息遵循 Conventional Commits”。这样无论是我自己还是同事使用 opencode，它都能遵守团队的规矩。

4. 实战：让 opencode 独立完成一个功能

4.1 动手前的思路：把任务拆到代理能“一口一口吃”

用 opencode 最容易犯的错误是一次性让它干太宏大的事。比如“把这个项目重构一下”这种需求，模型不是不能干，但它需要自己拆解规划，执行过程中一旦偏离方向，浪费的时间和 token 都很多。我的经验是先小步走。

每次只给它一个明确的小目标，比如“找出 user 模块里所有调用 remoteFetch 的地方，列出来”，或者“给 list 接口加分页”。小目标完成之后，检查 diff、确认没问题，再下达下一个指令。这就像带新人一样，你可以让它独立做，但要把阶段节点卡住。

4.2 一段真实的指令和它的执行过程

我拿一个真实场景举例。项目是一个 Express 写的老接口服务，需求是给用户列表接口加分页。我在 opencode 里输入的内容大致是这样：

先看 src/routes/user.js 里的 list 接口，介绍一下它现在怎么获取数据的。 然后给这个接口增加 page 和 pageSize 两个 querystring 参数， 默认 page=1、pageSize=20，返回体里带上 total 字段， 但要保证不传参数时的返回结构和原来完全一致。 改完后跑一遍 npm test 看结果。

这段指令里藏着三个关键点。第一，“先看…介绍一下”逼它先理解现状，而不是直接动手改；第二，明确写清楚默认值和兼容性要求，这是验收标准，模型知道你在考核它；第三，让它自己跑测试，形成闭环。

执行时它会在终端里自动调用各种工具，能明显看到它先用搜索工具找接口定义，再用编辑工具改代码，最后执行测试命令。整个过程像在看一个真实同事操作，只不过动作全部发生在你的眼皮底下。

4.3 让代理自己跑测试和修 bug

很多人用 AI 编程工具只让它“写代码”，不让它“验证代码”，这是巨大的浪费。opencode 的优势在于它可以直接执行命令，所以你在指令里养成带“跑测试”的习惯，就等于让它对自己交付的代码负责。

有一次我让它修一个并发问题，它改完后自动执行了项目的集成测试，结果有一处用例失败。它没有把这个失败留给我，而是自己回看代码，发现是全局单例被污染了，然后补了一个清理逻辑，再跑，测试全绿。这种“发现问题 → 分析原因 → 修 → 再验证”的循环，才是代理式开发比聊天窗口插件强得多的原因。

这里要说明一下，它执行命令是受控的。opencode 在 plan 和 act 两种模式之间可以切换：plan 模式只读分析和规划，act 模式才会真正改文件、跑命令。拿不准的时候先用 plan 让它给出方案，你确认之后再切 act，这样能避免模型脑补出一堆不必要的改动。

4.4 审查 diff：代理式开发里最重要的一步

无论 opencode 多顺滑，代码审查这个环节绝对不能省。每次它改完代码，我会立刻执行git diff逐行看。这不只是把关质量问题，也是在给模型做“行为校准”。

比如它把查询条件直接拼进了 SQL 语句，我会在对话里说：“这里应该用参数化查询，不要把用户输入拼进 SQL。”它下次遇到类似问题就会规避。这种反馈成本很低，但积累起来效果很明显——你用同一个配置越久，它越了解你的编码偏好。

反过来，如果发现它改乱了，最好的办法不是说“你错了”，而是指出具体文件和行号，给出你期望的行为。这样它能在最小范围内调整。我遇到过几次模型大面积重写代码的情况，都是因为我的指令里给了它太多发挥空间，后来把指令改成“最小改动”四个字，情况立刻改善。

5. Skills、记忆和 IDE 联动

5.1 Skills：把重复方法论固化成指令包

用 opencode 一段时间后，你会发现自己反复让它做几类任务：提交信息、代码审查、接口文档生成、单元测试补充。与其每次重复写一大段 prompt，不如把这些方法论封装成 Skills。

Skills 本质上是一组 markdown 指令，在对应任务出现时自动加载给模型。目录结构很简单，全局 Skills 放~/.config/opencode/skill/，项目级放.opencode/skill/，每个技能是一个子目录，里面有一个SKILL.md文件。我拿一个代码审查技能举例：

--- name: code-review description: 对当前分支的改动执行一次代码审查 --- 1. 先运行 git diff 查看当前分支相比主分支的改动 2. 按严重程度从上到下给出问题清单：阻塞问题、逻辑问题、风格问题 3. 对每个问题指出对应文件和代码片段，并给出修改建议 4. 不要修改代码，只输出审查报告

配置好后，我在输入框里敲一句“帮我审查一下这次改动”，opencode 就会自动套用这套流程，而不是临场自由发挥。它解决了“模型不是不会做，而是每次问法不同导致回答质量波动”的问题。

5.2 Memory 和 AGENTS.md：让 opencode 记住你的偏好

模型每次会话都是全新的，它不记得你昨天的偏好，除非你把偏好写下来。opencode 的解决方式是“可检索的长期记忆”。全局层面，你可以在配置目录放一份 AGENTS.md，写清楚通用的编码规范；项目层面，在.opencode/目录下放项目专属约定。

我自己的全局 AGENTS.md 里写着“变量命名使用有语义的完整单词，禁止单字母变量”“提交信息用 gitmoji 风格”“测试文件与被测文件放同一目录”。项目级 AGENTS.md 则写“本项目的日志统一用 pino”“改动必须兼容 Node 16”。

这套机制用起来之后，你会明显感觉到两个不同：一是首轮对话的准确率大幅提升，因为模型已经知道你的规则；二是纠正次数减少很多。对个人开发者来说，这就是“越用越懂你”的实现方式。

5.3 VSCode、IDEA 和桌面版的正确用法

opencode 最纯粹的用法是独立终端，但如果你不想频繁切窗口，也可以把它嵌进 IDE 里。在 VSCode 里搜索 opencode 扩展，装好后侧边栏能直接开一个 opencode 面板，本质是把终端 TUI 搬进了编辑器，好处是看代码和对话都在同一窗口里。

JetBrains 系（IDEA、WebStorm 等）同理，虽然部分版本没有官方插件，但它的集成终端完全能胜任。Ctrl+Tab 切到终端、转发端口都在同一个窗口，实际用起来已经足够顺手。我个人的建议是，重度开发时用独立终端启动 opencode，浏览代码和轻量修改才用 IDE 内嵌方式。

至于 opencode 桌面版，它并不是一个和 TUI 并列的新形态，更多是给不想用终端的人加了一个图形壳。功能上该有的都有，但如果你已经熟悉终端操作，桌面版带来的增量不大。我的看法是：工具形态不重要，找到最适合你自己的入口方式才是关键，桌面版适合团队里对终端有心理门槛的同事。

6. 常见报错排查与我的避坑清单

6.1 命令找不到：Windows 的 PATH 问题

这个报错在 Windows 上太常见了，报错原文大概是：opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因就是 npm 全局安装后的目录没有加入系统 PATH。

解决办法分两步。先执行npm prefix -g查看全局目录路径，在 Windows 上通常输出的是C:\Users\你的用户名\AppData\Roaming\npm，然后把这一整段路径加到系统环境变量的 PATH 里。加好之后重开终端，opencode就能识别了。

如果不想动环境变量，临时方案是用npx opencode启动，或者干脆在项目里用 npm scripts 包一层。但长期用建议还是把 PATH 修好，毕竟每次 npx 都要检查远程版本，启动速度会慢一些。

6.2 unexpected server error：八成是模型配置问题

另一个高频报错是error: unexpected server error. check server logs。第一次遇到，看日志会看到一堆请求层面的错误，但根源往往不在你本机，而在配置。

我的建议是遇到这个报错先不要死磕 opencode，按顺序做三件事：确认服务地址可达、确认密钥有效、确认模型名准确。九成问题出在这三个地方，而且每一步都能用简单命令独立验证，比盯着 opencode 日志猜快得多。

6.3 终端渲染异常、模型回答不稳定

如果 opencode 界面出现乱码、布局错位、按快捷键没反应，先换终端验证。现代 TUI 程序对终端能力要求不低，旧的终端模拟器很容易触发这种问题。我在 Windows 上就碰到过在传统 cmd 里启动正常、但功能按键全部失效的情况，换到 Windows Terminal 后一切正常。

模型回答不稳定则是另一回事。同一个指令，不同模型的表现差异很大，同一个模型在不同上下文长度下的表现也可能波动。我的经验是，模型回答不好时首先检查上下文是否塞了太多无关内容，过长上下文会导致模型注意力分散；其次才考虑换模型。

另外，如果你本地跑小模型觉得回答质量差，不一定是你配置问题，大概率是模型能力上限就在那。本地模型适合简单机械任务，复杂业务逻辑还是得上能力更强的云端模型，花点钱买了稳定，反而节省调试时间。

6.4 一套能救命的常规排查顺序

最后我把自己常用的排查顺序整理成清单，每次出问题就按这个走一遍，基本能覆盖九成场景。

第一，确认 opencode 版本不是太旧，opencode --version看版本号，必要时升级。第二，确认网络与配置，检查 baseURL、API Key、模型名这三个铁三角。第三，确认本地依赖服务都在跑，Ollama 有没有启动、数据库有没有连上。第四，清空或缩减上下文，有些问题纯粹是上下文太长导致的幻觉或报错。第五，去看日志，日志里会有更精确的错误信息，虽然啰嗦，但至少能指出方向。

这套顺序的核心思路是从“外部因素”开始排查，再到“工具自身”。不要一上来就怀疑 opencode 坏了，多数时候问题出在模型配置和依赖环境上。

最后再分享一个我个人的实际心得：现在让我回到只用图形化 AI 插件写代码，我已经不太习惯了。倒不是图形工具不好，而是 opencode 这种“能看代码、能跑测试、能改文件”的代理式工作流，帮我省掉了大量的上下文搬运成本。但我也要说句公道话，如果你接手的项目构建特别复杂、测试要跑十几分钟，那我还是建议先把构建和测试环境彻底弄顺再交给代理，否则你会把大量时间浪费在等待和误判上。先把基础环境弄干净，工具才能真正发挥价值。