如果你和我一样，已经受够了在各种 AI 编辑器插件之间来回切换，那可以试试 OpenCode——一个跑在终端里的开源 AI 编程代理。它不占编辑器、不锁工作流，直接把大模型的能力接到你的代码仓库上，能自己读代码、跨文件修改、执行命令、看报错再改。它不是那种单词补全工具，而是一个需要你“派活”、授权、验收的自动化助手。
这篇文章我会从安装配置开始，一直讲到权限控制、上下文管理、踩坑实录，尽量把我在真实项目里用下来的经验都写清楚。适合想把手头开发流程自动化、或者想研究 agentic coding 的人。新手可以先照着跑通一个小项目，老手可以直接跳到后面的安全部分。
1. 先搞明白 OpenCode 到底是个什么东西
1.1 它和“AI 补全插件”不是一类东西
用过不少代码生成工具的人都有一个共同的感受：补全插件在写单行函数、胶水代码的时候确实香，可一旦遇到“帮我重构这个模块”“把这份代码的错误处理补全”这种跨文件任务，它就歇菜了。因为补全插件的模型只能看到当前文件的一小段上下文，它对整个项目的依赖关系、历史约定一无所知。
OpenCode 的思路不一样。它更像一个“外包的实习生”：你给一句需求，它自己读文件、自己规划、自己改代码、自己跑命令看结果，不合适再继续改。你不需要一行一行地接受建议，只需要在关键节点上把把关。
我用一个生活化的类比来形容：普通补全插件是“输入法”，你打一个字它猜一个字；OpenCode 是“实习生”，你把任务交代清楚，它给你交一版草稿，你再提意见，它再改。前者降低的是打字成本，后者降低的是“从零开始理解任务”的成本。
这个本质区别决定了使用习惯也要变。你不能再期待它每次都给出一个“魔术般正确”的答案，而是要学会拆任务、定边界、观察它执行的中间过程，然后迭代纠偏。
1.2 为什么是命令行形态
很多人的第一反应是：现在插件这么发达，为什么非要做一个终端工具？其实命令行形态是一个刻意选择，不是技术上的偷懒。
命令行工具不依赖某个编辑器的图形界面，所以它的适用场景拓宽了很多。它可以在 CI 流水线里跑，可以在远程开发机上跑，可以被脚本调用，也可以同时处理多个仓库。我日常最常用的一种方式就是把它挂到代码合并请求的流水线里，自动给改动生成检视意见。团队里的同事不需要在本地装任何东西，在网页上就能看到它输出的评审列表。
另外，命令行天然更容易限定权限和输出。它能非常清楚地暴露“我现在读了哪个文件、我要改哪个文件、我要执行哪条命令”，这些信息被结构化地展示出来，方便调试和审计。
1.3 核心工作循环
OpenCode 的工作流程，本质上是一个可以不断循环的“计划-执行-检查”循环：
- 接收任务描述。
- 初始化上下文，载入仓库文件索引和配置。
- 模型生成动作计划，比如读取哪些文件、修改哪些文件、执行哪些命令。
- 代理按计划执行动作，观察返回结果。
- 结果不满足条件，就回到第 3 步继续生成下一轮动作。
- 任务完成，输出摘要或提交结果。
你一定要把这个心智模型刻在脑子里：它不是一个“问答机器人”，而是一个被赋予执行权限的代理。所以你给它一个模糊指令，它并不会像搜索引擎那样给你一个参考答案，而是真的会在你的仓库里动手。这也意味着，你需要像带新人一样给它清晰的任务边界和验收标准。
2. 安装与初始化：5 分钟让它跑起来
2.1 安装前的准备
在跑 OpenCode 之前，你需要确认几样东西：
- 一个较新版本的 Node.js 环境，因为 OpenCode 本身是 Node 生态的工具。
- Git，这个一般开发机都有。
- 一个大模型接口，云端商用接口或本地模型服务都可以。OpenCode 自身不带模型，它只是一个调度员，负责把仓库上下文组织好、再交给模型推理。
- 如果你用的是本地模型服务，那需要先把模型服务跑起来，确保本机某个端口能返回响应。
很多人在安装前最容易卡住的是“模型从哪来”。我的建议是第一次先用最简单的云服务接口，把端到端流程跑通，再考虑本地模型。因为你只有先看到代理完整地跑完一轮“读文件-改代码-跑命令”，才能真正理解它的能力边界，后面调本地模型才有对照基准。
2.2 安装 OpenCode
安装命令很简单：
npm install -g @opencode/cli opencode --version如果你不想污染全局环境，也可以用容器方式跑，官方镜像里已经把运行时和基本依赖打包好了：
docker run --rm -it \ -v "$PWD":/workspace \ -w /workspace \ opencode-image容器方式比较适合“不想让代理直接接触本机文件系统”的人，或者需要固定版本做回归测试的团队。日常个人开发，全局安装更方便，因为可以直接在任意目录打开终端使用。
2.3 配置模型提供商
安装完成后，先执行初始化命令：
opencode init它会生成一个配置文件，里面主要包含模型提供方、模型名称、接口地址、权限规则等。下面是我常用的一份配置，你可以照抄改改：
{ "provider": "local", "model": "local-coder:14b", "baseURL": "http://localhost:11434/v1", "apiKeyEnvVar": "OPENCODE_API_KEY", "permission": { "confirm": "danger", "read": ["./src"], "write": ["./src"], "commandWhitelist": ["npm test", "npm run lint", "git status"] } }稍微解释一下几个关键点。
baseURL指向本地服务时，OpenCode 会直接用 OpenAI 兼容的接口格式去请求。很多本地推理框架都支持这种兼容模式，你只要把地址换成“http://localhost:端口/v1”就行。
如果你用的是云端接口，不要把 key 写到配置文件里，应该通过环境变量注入：
export OPENCODE_API_KEY="你的密钥"配置文件里只写"apiKeyEnvVar": "OPENCODE_API_KEY"，这样密钥就不会进入版本库，也不会因为代理误读代码被带出来。
permission是权限控制，这个极其重要，我在第 4 节会详细展开。新手阶段，直接把confirm设为"danger"，让代理遇到危险命令时停下来问你。
2.4 第一次对话
配置完成后，在项目目录下运行：
opencode看到提示符之后，输入：
请先阅读 src/main.js，然后用中文解释一下这个项目是干什么的，以及入口流程。不要修改任何文件。注意后面那句“不要修改任何文件”，即使当前的配置下它可能没有写权限，但多一句明确的约束能减少误操作。你会发现它的输出会先列出“读取文件”的动作，再给出总结。这一步主要是让你熟悉动作日志的展示方式，后面观察危险动作时靠的就是这段日志。
3. 把 OpenCode 用起来：五个我天天在用的场景
3.1 代码解释与获取全局视角
接手一个陌生项目时，我通常会用 OpenCode 快速建立全局认知：
解释一下这个仓库的整体架构，主要关注 src/ 目录下的模块依赖关系，输出一份 markdown 表格。不要修改任何文件。相比于自己翻文件，这个方式快得多。尤其在旧项目里，文档经常是过期的，代码才是真相。OpenCode 能同时在多个文件之间建立关联，输出一个比较完整的模块关系图，我再人肉验证一遍关键节点，很快就能上手。
但这里要提醒一句：模型的解释不一定全对，尤其是面对高度耦合的遗留代码时，它可能得出一个“看起来合理但实际并不准确”的结论。所以我的习惯是把它当成“第一版草稿”，让我知道该往哪个方向深入，而不是直接采信。
3.2 跨文件重构
这是 OpenCode 最出彩的场景，但也是最容易翻车的场景。我的一个模拟项目里有一个核心文件超过两千行，我想把业务逻辑拆到独立的 service 文件里。如果手工改，至少要半天；用 OpenCode，我给的提示词是这样的：
目标：把 src/controller.js 中的用户验证和业务逻辑拆分到 src/service/userService.js。 约束： - 保持对外接口与路由路径不变。 - controller.js 里只留下路由定义和参数校验。 - 拆分后必须运行 npm run lint 和 npm test。 - 不要动其他未说明的文件。 验收标准：所有测试通过，lint 通过，且 module.exports 的结构保持兼容。这个提示词的关键在于“验收标准”。对代理来说，任务描述里有没有验收标准，直接决定它会变成一个埋头乱改的工具，还是一个能自我检查的质检员。它执行完会自己跑测试，测试过了它才认为任务完成，没过它还会继续修。
在让代理动手前，我强烈建议先让它输出计划。你可以加一句：
先不要改代码。请阅读相关文件后，输出一份重构计划，包括新建文件、要修改的函数、预估影响范围。等我说“开始”再动手。这一步能提前纠正很多偏差。比如它想把接口语义也改了，或者想顺手重构根本不相关的地方，你在计划阶段就能按住它。
3.3 跑测试和修 bug
AI 编程代理最有价值的能力不是写新代码，而是“能自己验证修改是否正确”。我把这个场景排在第二重要的位置。
假设你现在有测试失败了，可以让它直接排查：
当前 tests/ 目录下有 3 个用例失败。请先运行 npm test 查看失败信息，然后修复相关源码，最后重新运行测试直到通过。如果修复不了，把失败原因和猜测写进 issues/failing-test.md。这一段提示词虽然短，但包含了完整的行动闭环：先看报错，再改代码，再验证，失败就记录。代理在执行过程中会自己去读测试文件和对应的源码，可能还会补充打印日志来定位问题，整个过程你可以像看直播一样观察它的动作。
为什么建议先让它“运行测试”，而不是直接把报错贴给它？因为很多报错信息是动态的，它自己跑一遍能拿到当前仓库的真实状态，避免基于过期信息做判断。而且，让它养成“动手前先验证环境”的习惯，能减少很多无效修改。
3.4 自动生成提交信息
写提交信息是我觉得性价比最高的用法。尤其改动跨多个文件时，人工总结容易遗漏，交给它做可以省很多事：
git diff | opencode --pipe "请分析下面的 diff，生成符合 conventional commits 规范的提交信息，并说明影响模块"注意--pipe模式下它没有仓库上下文，只处理传入的文本。所以这个方法适合改动不大、目标明确的 diff。如果我需要更高质量的提交信息，我会直接在交互模式下说“分析当前 git diff 并生成提交信息”，这样它还能结合最近几条提交历史来模仿团队的提交风格。
实际用下来的感受是：它生成的初始提交信息经常有点啰嗦，但主干结构是对的。你只需要删掉那些夸张的形容，留下“做了什么、为什么做、影响哪些模块”就足够了。
3.5 代码审查
我把它用在合并请求的前置检查里。流程是这样：
- 先跑一遍项目自带的静态检查工具，把格式、明显问题过滤掉。
- 然后在命令行执行
opencode review，让它基于 git diff 做逻辑层面的审查。 - 人工把它的输出和真正的改动意图对比，筛选有效建议。
审查时我一般会限定维度，不然它给出的内容会太宽泛：
请基于当前改动，重点审查以下维度： - 异常处理是否完善 - 是否有明显性能瓶颈 - 边界条件是否覆盖到 - 事务和资源是否有泄漏风险不带维度的话，它经常给出“缺少注释”这类没有信息量的建议。把维度限制住，审查结果的质量会高很多。不过最终的审查结论永远要人来定，因为它没有业务上下文，很可能会把“故意这么写的兼容逻辑”当成 bug，你要做的不是全盘接受，而是在它指出的问题中找到自己遗漏的地方。
4. 真正要命的安全与权限问题
4.1 代理的两大风险
看到这里，可能有人已经觉得它很省心了。但我要泼一盆冷水：这类能自主执行命令的 AI 代理，风险比传统代码补全工具大得多。主要的威胁有两个。
第一是提示词注入。仓库里可能存在来历不明的代码、第三方依赖的文档、甚至某个 Markdown 注释，里面藏了恶意指令。模型只要读到这些内容，就可能被引导去执行危险操作。这不是理论上的担忧，在实验环境里我就遇到过：一个故意构造的 README 注释，让代理试图删除临时目录下的所有文件。
第二是误执行危险命令。模型生成的命令不一定符合你的真实意图，它可能把rm -rf只用在临时目录上，但如果路径拼接出错，破坏范围就会扩大。它也可能在你没注意的情况下执行了git push，把半成品代码推上远端。
所以，用 OpenCode 之前，必须先建立一道安全防线。
4.2 权限控制机制
OpenCode 的权限配置主要有三类：文件读写限定、命令白名单、交互确认。它们可以组合使用。
"permission": { "confirm": "danger", "read": ["./src"], "write": ["./src"], "commandWhitelist": ["npm test", "npm run lint", "git status", "git diff"] }read数组限制它只能读哪些目录。不在列表里的路径，它没有访问权限。write数组限制它能修改哪些目录。我只给了src，这样即使它思路跑偏，也无法去改配置文件、部署脚本或.env。commandWhitelist是可自动执行的命令列表。不在列表里的命令，必须经你确认。confirm: "danger"表示只有危险命令才触发确认，普通白名单命令自动执行。
我的建议是：无论你有多信任模型，都保持最小权限。它只是你的“实习生”，你没有必要把房产证和备用钥匙都给它。现实中你请装修工人，只会让他进客厅干活，不会把整个家的钥匙都交出去。
4.3 在隔离环境里跑
想进一步降低风险，可以把 OpenCode 放进容器里跑。这样即便代理真的执行了破坏性命令，它也只能影响容器内部的文件系统，不会波及宿主机。
一个简单的做法：
docker run --rm -it \ -v "$PWD":/workspace \ -w /workspace \ opencode-image但要注意，如果让容器完全断网，代理也访问不了模型 API。实际使用时，你需要根据模型地址放开对应网络访问，通常用主机网络的模式就可以。关键是让脚本和命令在容器内执行，文件挂载用只读或部分可写的方式。
如果你在处理特别敏感的代码，还可以配置“只读模式”，让代理只能读文件、不能写文件。这样你可以在它执行分析、生成计划、跑代码审查的时候放心使用，等确认计划没问题，再换成可写模式让它动手。
4.4 API Key 管理
另一个容易忽略的坑是 API Key 泄露。
不要把它写进配置文件里。坏处有两点：一是配置文件可能被提交到版本库，二是代理在遍历仓库时也会读到配置，等于把你的密钥直接喂给模型。正确做法是使用环境变量注入：
export OPENCODE_API_KEY="你的密钥"同时，把.env、*.pem、*key*这类文件加入忽略列表。我建议在.opencodeignore里至少加上：
node_modules/ dist/ build/ coverage/ .env *.local忽略这些文件，不仅能防止密钥被读走，也能减少无效文件的解析，节省 token 开销。
5. 把模型调教得更听话：提问与工程化经验
5.1 上下文管理技巧
代理的工作质量，一半看模型，另一半看你怎么组织上下文。一个非常常见的错误，是让代理直接处理整个大型仓库——相当于让第一次进公司的新人一口气读 20 本书，结果什么都记不住，回答自然越来越混乱。
你需要主动控制它能看到什么。.opencodeignore就是给代理做减法的地方。除了node_modules和构建产物，我还经常把测试夹具、文档、配置文件也排除掉，只保留核心源码。这样它能聚焦在真正需要修改的业务代码上。
如果仓库本身很大，比如 monorepo，我会在提示词里限定路径：
只关注 packages/service-a 下的内容，不要读取其他 package 的代码。这个措施不是可有可无的优化，它能直接决定任务能不能完成。模型输入的注意力是有限的，塞了太多无关代码，它会“顾此失彼”。
5.2 给任务定一个模板
我用了一个非常稳定的任务描述模板，几乎每次都有效：
【目标】一句话说清楚要做什么。 【背景】项目技术栈、相关模块、关键文件。 【约束】不要改哪些文件，必须保留哪些接口。 【步骤】如果希望它按特定顺序执行，写清楚步骤。 【验收】它必须能自己判断是否完成，例如“测试通过”“没有语法错误”。模板的核心是“约束比命令更重要”。模型不是不会做，而是一开始就理解偏了。给它足够多的边界，它会像一个训练有素的工程师一样按部就班地推进；边界太少，它就会自由发挥到没法收拾。
5.3 分步执行，而不是一次梭哈
复杂任务最大的失败原因，不是模型能力不够，而是一开始方向就错了，后面全是在错误地基上打补丁。
所以我现在基本都开着“计划模式”。先让代理只输出计划，不碰任何代码：
先不要改任何代码。请阅读这些文件后，输出一份执行计划，包括要新建的文件、要修改的函数、影响范围。等我说“开始”再动手。它会输出一个计划列表，你在这一步把偏差纠正掉，再放行让它执行。虽然多了一个来回，但成功率明显提升。对于超过 3 个文件的修改任务，这个流程几乎是必须的。
5.4 多模型切换的配置策略
OpenCode 允许你配置多个模型，按任务类型切换。这不是炫技，而是成本和质量的平衡问题。我目前的做法是：
| 场景 | 模型规格建议 | 原因 |
|---|---|---|
| 复杂重构、跨文件计划 | 能力更强的大参数模型 | 推理和规划能力更强，能处理长链路任务 |
| 简单问答、生成提交信息 | 轻量或本地开源模型 | 响应快、成本低，完全够用 |
| 敏感代码分析 | 本地模型 | 避免敏感代码被上游服务留存 |
切换模型的操作很简单，只需要在启动时指定配置名称，或者在配置文件里写多个 provider，交互时切过去就行。
大参数模型的价值不是“更聪明”，而是更能在一长段上下文里保持逻辑一致。所以别拿大模型去生成 commit 信息，那是杀鸡用牛刀；也别拿小模型去重构跨模块的代码，它会做一半就前言不搭后语。
6. 实际踩坑与解决实录
6.1 亲历事故：代理自己删了文件
这是我刚用这类工具时踩得最惨的一次。当时在模拟项目 X 里，我让它清理冗余模块，提示词里写了“删除不再使用的模块”。它理解成整个工具目录都不再使用，直接把src/util/下面的文件删了个干净。
问题的根源在权限配置。那时候我还没启用提交前确认，代理对删除命令有完整的执行权，所以它执行完删除后已经无法撤销了。好在那次代码刚提交过，还能找回。
从那以后，我的配置里永远开着confirm: "danger"，而且凡是有“删除”“清空”“重置”这类破坏性操作的任务，我都会在后面追加一句“先列出你要删除的文件清单，等我确认后再执行”。
6.2 上下文太大导致模型“失忆”
有一次我让它分析一个大 monorepo，一上来就把几十个包的代码全部读进去，结果前几句话还正常，后面就开始答非所问，甚至反复引用不存在的文件。
后来我意识到，这就是上下文爆了。解决办法有两个：一是用忽略规则和路径限定，让它只关注相关模块；二是把大任务拆成几个小任务，每完成一步就让它总结当前状态，再继续下一步。
如果发现它已经明显“失去记忆”，最好的办法不是硬着头皮继续问，而是重启一个新会话，并把之前的结论复制进去。这个操作虽然看起来有点笨，但能立刻恢复质量。
6.3 模型生成的命令和仓库实际环境对不上
代理经常凭印象拼命令，比如它以为项目里装了某个检查工具，其实根本没有；或者它想用某个依赖的写法，但项目里的版本并不兼容。
解决方法是把命令白名单写得严格一点，同时告诉它：
在运行任何命令前，先查看 package.json 的 scripts 部分，只使用其中存在的命令。另外，把常用命令加入白名单，比如npm test、npm run lint、git status、git diff，不让它盲目执行名单外的命令。白名单外的命令它仍可以执行，但必须经过你确认，这样你可以在命令真正运行前判断它是否合理。
6.4 token 消耗比想象中快得多
AI 编程代理是 token 消耗大户。一次跨文件重构，我预计跑几百轮，结果实际消耗是预估的三倍。原因也很简单：它每读一个文件、每执行一次动作、每生成一轮计划，都在消耗 token，而且还需要反复读取文件来确认上下文。
控制成本的经验有三条。
第一，在配置里设置总步数上限，比如某一任务最多跑 20 轮，超出就自动停止。这能防止它陷入死循环。
第二，简单任务用轻量模型。不要所有请求都走大参数模型。
第三，长任务里主动让它“定期总结”。你可以每过几轮提示它：
请总结到目前为止的进展、已经改动的文件、剩余待办，然后再继续。这个操作能让它重新对齐上下文，避免反复从零读取文件，间接节省 token。
6.5 死循环：同一个文件反复修改
有一次它修一个 bug，连续五轮都在改同一个文件，而且每次改完测试还是失败，它就继续改，最后越改越偏。
我现在的做法是在大任务描述里加一句：
如果同一处逻辑修改超过 3 次仍未解决，请停止修改，输出你的分析和猜测。这句话几乎每次都能救场。模型确实会在失败时进入“执念”状态，强制设定止损条件，能让它停下来汇报，而不是继续消耗资源。
最后说几点个人体会
用了 OpenCode 大半年，我最大的感受是：它改变的不是写代码的速度，而是你对待任务的拆解方式。你需要像一个项目经理一样，去描述目标、约束和验收标准，代码反而是最后一步。所以如果你正打算上手，我的建议是：先从一个小型练习仓库开始，打开计划模式和确认模式，先观察它怎么思考，再慢慢放开权限。把它当作一个能力很强但经验不足的新同事，你会用得更顺手，也会少踩很多坑。
