OpenCode 终端 AI 编码助手：从安装到自定义 Agent 实战指南

我刚开始接触 OpenCode 的时候，其实并没有抱太高期待。AI 编程助手我前前后后试过不少，编辑器的、独立客户端的、各种插件拼装出来的“全家桶”方案都有，但用下来的感觉就是，真正干活的时候，总得在好几个窗口之间来回切，上下文还经常对不上。OpenCode 是个例外，它是一款跑在终端里的开源 AI 编码助手，可以让你在命令行里直接和代码库对话，让 AI 自己去看文件、改代码、跑命令，像一个拥有项目全局视野的结对搭档。这篇文章我会从安装配置讲起，一路聊到自定义 Agent、MCP 扩展和自动化脚本，把我这几个月实际使用踩过的坑、养成的习惯一起写出来，给想从零上手 OpenCode 的朋友一份比较完整的参考。

1. 为什么我会从“编辑器内置 AI”折腾到“终端 AI 助手”

1.1 工作方式的转变

先说个实际场景。以前我修一个 bug，通常要经历这么一轮：先在编辑器里翻代码，定位可疑文件，然后在脑内整理调用链，再用命令行跑测试确认，最后回头改代码。看起来每一步都很正常，但问题在于，真正消耗精力的不是“改”，而是“找”。一个项目上百个文件，AI 如果只停留在聊天框里，它看不到你的代码库，就只能瞎猜。

于是就有了终端 AI 助手的思路：工具本身运行在项目目录里，它可以通过命令去列目录、读文件、搜索符号定义、执行测试，把上下文真正建立在你当前代码的基础上。OpenCode 做的就是这件事。它不是又一个聊天窗口，而是一个能操作你项目的 agent。你给它一个目标，它会自己规划步骤，调用工具完成调查和修改，再把结果拿回来和你确认。

我选择 OpenCode 还有一个很朴素的原因——开源。工具本身完全开源，本地数据都在你自己机器上，没有私有协议和数据锁定的问题。出于长期使用的考虑，这一点让我安心很多。

1.2 和其他 AI 编程工具的差异

我经常被问到“这类工具那么多，为什么偏偏用它”。这里我列一个简表，大家可以根据自己的需求去判断。

当然，编辑器内置 AI 也有它的优势，比如补全延迟低、熟悉你的 style。但如果你经常需要处理“跨文件理解”“整块重构”“修完还要跑测试”这类完整任务，OpenCode 这种 agent 模式明显更顺手。它把 AI 从“回答问题的人”变成了“能上手干活的人”。

2. 安装、密钥与初次配置

2.1 安装方式：两条主流路径

OpenCode 的安装我试过两种方式，都挺简单。第一种是官方提供的安装脚本，一行命令搞定：

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

这种方式适合大多数平台，脚本会自动下载对应版本的二进制文件并配置好环境变量。如果你不太放心直接把脚本管道给 bash 执行，也可以先下载脚本看一眼再做决定。

第二种方式是通过 npm 全局安装：

npm install -g opencode-ai

这种方式要求你机器上有 Node.js 运行时。装完之后同样会提供opencode命令。两种方式选一个就行，个人习惯用官方脚本，升级也更加直接。装完可以用opencode --version确认是否成功。

2.2 API Key 环境变量配置

OpenCode 本身不提供模型，需要接入你已有的模型 API。模型服务商的选择取决于你自己，常见的有 OpenAI 系、Claude 系、以及一些兼容 OpenAI 格式的本地模型服务。当前 OpenCode 支持多模型配置，启动前把 Key 注入环境变量即可。

以 bash/zsh 为例：

export ANTHROPIC_API_KEY="你的key" export OPENAI_API_KEY="你的key"

这里有一个很重要的习惯：不要把 Key 写死在项目里。哪怕项目只有你自己在看，只要哪天提交到 Git，key 可能就泄露了。正确做法是放在环境变量里，或者放进本地配置文件中，并且确保 Git 会忽略它。

如果你希望每次打开终端都自动带上这些变量，可以加到~/.bashrc或~/.zshrc末尾，然后用source刷新。这个细节我踩过坑，一开始只图省事，在脚本里写死 key，后来发现一个临时文件混进了提交记录，只得紧急轮换，惹了不少麻烦。

2.3 全局配置文件的组织方式

OpenCode 的配置目录通常在~/.config/opencode/，里面可以放一个opencode.json配置文件，用来管理 provider、默认行为和扩展项。我的基础配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "openai": { "api_key": "env:OPENAI_API_KEY" }, "anthropic": { "api_key": "env:ANTHROPIC_API_KEY" } } }

注意这里我特意没有写死模型名，因为我想在交互界面里按任务切换模型，避免某个模型在配置里被固定住，实际运行时反而限制了自己的灵活性。env:OPENAI_API_KEY的意思是让工具去读取当前环境变量中的OPENAI_API_KEY，这样配置文件和密钥就彻底分开了。

另外一个经验是：配置文件尽量只放长期有效的内容，比如 provider 列表、默认的行为偏好；临时性的参数用命令行参数或交互命令去处理，别在配置文件里堆一堆临时开关。OpenCode 版本迭代很快，配置项会调整，写得越精简，升级时越少折腾。

3. 从启动到完成第一个真实任务

3.1 启动交互界面

进入一个项目目录，直接运行：

cd /path/to/project opencode

启动后会进入一个交互式终端界面，界面上方通常显示当前会话使用的模型，底部是输入区。你可以像聊天一样输入自然语言，也可以输入斜杠命令来控制会话。初次使用的人最容易忽略一件事：当前工作目录就是 AI 的“视野范围”。所以先cd到正确的项目目录再启动，非常关键。

第一次打开时，如果配置了多个 provider，它会询问或允许你切换使用哪个模型。我个人建议第一句话不要直接提需求，而是先让它了解项目结构。你可以试试：

先帮我整体介绍一下这个项目的目录结构和核心模块，不需要改代码。

这一步非常有价值。它相当于让 AI 先建立项目的地图，后续指定任务时准确率高很多。我见过很多人上来就丢一个需求，AI 由于不熟悉代码结构，给出的方案经常是“看起来合理但实际上没贴合现有设计”，原因就是缺少这个预热过程。

3.2 核心使用逻辑：工具调用

OpenCode 的核心不是“聊天”，而是“执行”。它会根据你的目标生成一个多步骤计划，然后依次调用工具完成工作。常见的能力包括：

• 列出目录和文件列表
• 打开并读取某个文件的内容
• 在代码中搜索关键词或符号
• 编辑文件内容
• 执行 Shell 命令，例如运行测试或构建

每一步执行前，对话界面会给你确认的机会，你可以允许、拒绝或者修改。这个设计非常重要。它把控制权保留在你手里，AI 要改某个文件前，你能先看到它的意图，避免误操作。

我的习惯是：读取、搜索这类只读操作直接放行；涉及修改文件、安装依赖、删除文件等高风险操作，仔细看清楚再决定。到现在我几乎没有遇到过不可挽回的误操作，反倒是因为我敢于在确认后放行，AI 可以连续做完“调查-修改-验证”整个闭环，效率高很多。

3.3 实操案例：排查一个测试报错

用一个非常典型的例子来说明完整流程。假设我在某个项目里跑测试，看到一段报错：

TypeError: formatDateTime is not a function at src/utils/format.js:18

通常我先自己打开文件看，但这次我直接把它丢给 OpenCode：

测试报错了，TypeError: formatDateTime is not a function，报错位置在 src/utils/format.js 第 18 行。帮我查一下原因，并给出修复方案。

OpenCode 的响应一般分几步。它会先打开src/utils/format.js，确认 18 行附近的代码，然后搜索formatDateTime的定义位置，发现它来自另一个工具函数文件。接着它会对比调用方和定义方之间的差异，定位到问题在于函数签名从两个参数改成了三个参数，但某处调用没有同步更新。最后它会给出修改建议，并且提示我改完后跑哪条测试命令来验证。

这段过程中注意两个点：一是它从一开始就主动使用了“读文件、搜索、对比”这类工具，而不是只靠猜测回答；二是它给我的不是一句“看起来是参数不对”这种空话，而是一份包含定位、原因、修改路径和验证方案的完整结果。这正是 agent 类工具和普通问答式 AI 的区别。

如果你让它直接修改，它会执行编辑操作，之后再帮你跑测试。跑完如果通过，就结束；如果不通过，它会继续看下一个错误，迭代修复。这种连续处理问题的体验，比人工一步步查要快得多。

4. 常用功能拆解：会话、模型与上下文管理

4.1 用斜杠命令掌控会话

进入 OpenCode 的交互界面后，输入/就能看到一组命令。我把常用命令整理成了自己的一个速查习惯：

• /model：切换当前会话使用的模型
• /new：开始一个新会话
• /compact：压缩当前会话上下文，保留关键信息
• /help：查看命令列表
• /mcp：管理外部工具扩展

不同版本对命令名称可能有细微调整，所以最靠谱的方法是随时输入/help查看。斜杠命令是会话层面的控制台，平时用得最多的就是/model和/compact，尤其当对话进入后段、上下文开始冗长时，/compact几乎是保命技能。

4.2 模型选择和切换策略

OpenCode 支持多个模型服务商和多种模型，这让它特别适合“按任务挑模型”。我的策略很简单：日常小改动、读代码、解释报错，用响应快、成本低的模型；整库重构、跨文件大范围改造、复杂逻辑推演，换成能力强、上下文更大的模型。

用/model切换模型不需要退出会话，当前对话的上下文还能保留。这在实操中很关键，如果要做“先分析、后修改”的任务，我会先用便宜模型把问题分析清楚，然后切换到强模型执行修改，最后再用便宜模型跑验证。听起来有点折腾，但实际费用能省不少，尤其在长会话场景下。

4.3 什么时候该开新会话

会话会积累上下文，上下文越长，AI 对后续问题的理解越模糊，响应也越慢，费用也越高。我有一个明确的判断标准：当一个任务的目标发生变化时，果断开新会话。

比如刚开始让 AI 帮忙排查一个登录流程的 bug，查完之后又想让它顺手优化另一个模块的实现——这两个任务分离比较远，如果继续在旧会话里做，AI 脑子里满是上一个任务的中间结果，容易出现“掺杂”和“答非所问”。正确做法是先/new开一个新会话，然后把新任务里必要的背景信息重新描述一下，它反而更专注。

另外，如果一个会话已经来回很多轮，AI 的回复开始变得重复、记不住早先的约定，这时不要硬撑，直接/compact压缩上下文，或者干脆开新会话。带着过长上下文工作，效果只会越来越差。

4.4 上下文来源与指定文件

AI 怎么知道你关心哪些文件？有两种信息来源。一种是它自己通过工具扫描项目、按需要读取文件；另一种是你在指令里主动指定文件路径和范围。

我建议在重要任务中两者结合。比如：

请重点参考 src/services/auth.js 和 src/api/user.js，分析登录接口为什么会出现 401 错误。

指定文件的好处是减少搜索成本、提高准确率。OpenCode 在需要时也能自己去查，但如果你心里已经有怀疑对象，直接指路会高效得多。模糊提问的代价是 AI 可能把时间花在无关文件上，最后还要靠你纠正。

4.5 文件读写和命令执行的边界

前面提到 OpenCode 会执行文件编辑和终端命令，这里展开讲一下边界。默认情况下，涉及修改类的操作都会请求确认，读取类操作通常可以直接放行。但具体行为可以调整，部分版本支持把某些操作设置为自动信任或自动拒绝。

我的建议是：读取和搜索默认放行没问题，写操作和命令执行保持“确认”或者“要求解释”。尤其涉及npm install、rm、git push这类命令时，多看一眼再批准，不丢人。AI 理解的指令和你的真实意图之间偶尔会有偏差，确认机制是最后一道防线。

5. 进阶玩法：自定义 Agent、MCP 与自动化

5.1 给 OpenCode 创建专属角色

用了一段时间后，你可能会发现通用的 AI 行为不够贴合自己的场景。比如有时我只希望 AI 给我读代码、做解释，根本不想让它改文件。这时可以自定义 Agent。

OpenCode 支持通过配置目录中的 Agent 定义来新增角色。大致思路是给 Agent 写一个 Markdown 文件，在文件头部用 frontmatter 声明它的名称、职责描述、温度参数和运行模式，正文写系统提示词。一个“只解释不改代码”的 Agent 定义可以长这样：

--- description: 代码解读助手，只负责解释逻辑 mode: subagent temperature: 0.2 --- 你是一位资深工程师，擅长用简洁的中文解释代码逻辑。请回答问题时给出关键依据，但不要修改任何文件，也不要执行任何会改变系统状态的命令。

把文件放到配置目录的 agent 子目录后，在会话里就能切换到这个角色。我实际用下来，这种角色分离的好处很明显：一个专门做代码审查、一个专门做重构、一个专门写测试，它们各自的提示词更聚焦，输出质量也更高，不会像通用 agent 那样“一会儿想改文件，一会儿想长篇大论”。

不过要提醒一点，Agent 的字段和用法在不同版本里有差异。我这里的写法是常见实践，具体以你当前版本的/help和官方文档为准。调试自定义 Agent 时，先从最简单的角色开始，确认能正常调用后再逐步加规则。

5.2 MCP 扩展：给助手接上外部能力

MCP 的全称是 Model Context Protocol，你可以把它理解为 AI tool 的“外接设备”。默认情况下，OpenCode 能操作的是项目文件和终端命令，而通过 MCP，它可以连接外部数据源或专用工具，比如数据库查询、文档检索、浏览器自动化等。

我在团队内部用过的一个典型场景，是接一个内部的接口文档检索服务。以前 AI 对项目里调用的接口定义一无所知，只能靠读代码猜测。接入 MCP 后，它可以主动去检索接口文档，把参数含义和返回结构作为上下文，回答质量和准确率直接提升了一个台阶。

MCP 的配置通常也写在 OpenCode 的配置文件中，给每个扩展起一个名称，绑定启动方式。不同 MCP 服务的配置写法会有所差异，我建议直接用交互界面的/mcp命令来管理，它能列出当前已加载的扩展，也可以动态添加、删除或停用。刚开始接 MCP 不要贪多，先接一个最实用的外部工具，跑通之后再去扩展其他能力，不然排错会非常痛苦。

5.3 非交互模式与自动化脚本

OpenCode 除了交互界面，还支持非交互式运行。也就是说，你可以把它当作命令行工具来调用，一条命令直接返回结果，适合放进脚本或自动化流程。

举个例子：

opencode run "找出项目中所有未使用的 import，并列出文件路径"

执行完后，结果会直接输出到终端。这样你可以写一个包装脚本，批处理多个任务，或者把它接进自己的工具链。如果需要基于上一次会话继续，可以去查找run命令的--continue参数，具体以当前版本的帮助为准。

我比较喜欢用它做代码审查辅助。比如先把代码提交到本地分支，然后用opencode run让它检查变更里有没有明显的问题，再人工复核它的输出。虽然不是所有问题都能被准确识别，但至少能把低级错误过滤一遍。想更进一步的，还可以把这类命令封装进一个脚本，让它在提交前自动执行并输出报告。

5.4 从个人工具到团队规范

当 OpenCode 在团队里普及之后，配置统一就变得重要了。我的做法是把配置文件版本化，提交到共享仓库，但密钥绝不入库，每个人用自己本地的环境变量。同时把团队约定的 Agent 角色放在统一目录里，让所有成员使用同一套提示词，输出风格会更一致。

团队刚开始推行时，不要一上来就要求所有人都用全套自定义角色。先让每个人用默认模式跑通一两个真实任务，再逐步引入团队统一的 Agent 和 MCP 配置。工具的接受度是靠实际效果建立的，而不是靠规章制度。

6. 我踩过的坑和问题排查思路

6.1 一上来就报鉴权错误

新手最常见的问题，是启动后模型列表为空，或者输入内容后立刻报鉴权失败。通常原因就是 API Key 没配置成功。

排查步骤很简单：

1. 先执行env | grep -i api_key，看看环境变量里是否真的有对应的 key。
2. 确认 key 本身有效，并且有通过该模型服务的权限。
3. 确认当前会话选中的 provider 和你自己设置 key 的服务商一致。

这里有个容易忽视的细节：某些服务商的 key 前缀有严格格式要求，复制的时候如果多了一个空格或换行符，测试时会一直报错且不好定位。我遇到过两次，最后都是因为终端复制粘贴时带上了多余空格。

6.2 会话说太满，AI 开始“失忆”

长会话进行到后半段，AI 的表现会明显下降，比如回答内容越来越泛、忘记你前面提到的约束。这不是玄学，而是上下文长度和注意力机制导致的自然现象。

应对方式有两个：一是用/compact压缩上下文，二是开新会话。压缩操作会保留对话中的关键信息，但丢掉一些过程性细节；如果任务已经切换，直接/new更干净。我自己的习惯是每完成一个子任务，就判断一下是继续还是开新会话。

6.3 AI 想改的文件改不了

有时候 AI 分析完了，给出的修改方案很合理，但一执行却报“文件受限”或“无法写入”。这个问题通常有三个原因：

• 当前用户对那个目录没有写权限
• 文件被 Git 忽略规则排除，工具默认不碰忽略文件
• 工具权限策略把你设成了“必须手动确认”，而确认被超时跳过

第一个原因去检查目录权限；第二个原因打开 Git 忽略配置看看；第三个原因，回到权限设置里调整策略即可。从安全角度看，第二种限制实际上是在保护你，最好别为了省事强行绕过。

6.4 AI 改了代码，但我后悔了

虽然确认机制可以减少误操作，但总有手快的时候。如果真的改坏了，最稳妥的恢复方式是靠版本控制。依赖 Git 的日常流程，改动前保持工作区干净，AI 修改后先git diff检查，再决定保留还是丢弃。

这也是我为什么建议在真实项目中尽量把工作区维持在“有一份干净基线”的状态。如果 AI 动了一大批文件，而你的工作区本身就很乱，你很难区分哪些是它改的、哪些是自己之前的改动。干净基线加上git diff，几乎能解决所有后悔药问题。

6.5 常见问题速查

7. 一些个人经验，留给你少走弯路

7.1 从一个小任务开始，而不是拿它炫技

刚上手时，不要一上来就丢一个大重构任务。我建议先找一个几分钟能完成的小任务，比如“解释某个函数的逻辑”或“给这段代码补注释”，把界面操作、确认流程、会话管理这些都摸熟，再用它处理更重要的工作。这和一切新工具的规律一样，从简单场景建立信任感，之后再慢慢扩大范围。

7.2 始终保留“人是最终决策者”的边界

OpenCode 再强，它给出的方案也只是建议。我的原则是：让它做调研和初稿，但关键决策和最终验收一定自己做。特别是涉及架构调整、接口变更这类影响范围大的改动，AI 给出的方案可能局部合理，但缺少对项目未来演进的长期判断。核心决策别甩手交给工具，这是我对所有 AI 编程助手的通用态度。

7.3 一个好用的提示词模板

最后分享一个我常用的结构化提示词，放到 OpenCode 里很顺手：

背景：项目是一个 XXX 服务，技术栈是 XXX。 目标：修复登录接口返回 401 的问题。 范围：参考 src/services/auth.js 和 src/api/user.js。 要求：先分析原因，再提修改方案；改完后跑相关测试，并告诉我结果。 约束：不要修改无关文件，不要执行任何破坏性命令。

这套模板的好处是把“背景、目标、范围、要求、约束”都说清楚了。一开始你可能觉得麻烦，但你会发现 AI 的理解准确率明显提高，返工也少了很多。语言模型说白了就是一个非常依赖输入质量的执行器，输入越清晰，输出越可控。

用 OpenCode 这几个月，我最深的感受是，它把我从“重复定位代码和确认上下文”的低效劳动里解放了出来，让我更专注于设计和决策。自动化和工具是辅助，真正让项目推进的仍是人的判断和方向感。如果你正准备开始折腾这类工具，希望你也能玩得顺手，少踩我踩过的坑。