1. 打开工具箱opencode的“手”和“眼”1.1 内置工具模型不是直接碰代码的很多刚接触opencode的朋友会把它当成一个“能聊天的终端”但真正拉开它和普通AI对话差距的是一套内置工具。简单说模型本身只是个会“想”的大脑真正让它能读文件、改代码、跑命令的是工具。opencode在这点上的设计很直白工具被定义为一系列可调用的函数模型根据对话内容决定调用哪个、传什么参数然后拿到返回值再继续推理。这种“推理—调用—观察—再推理”的循环就是整个Agent工作的核心。打开会话后输入/tools能看到当前模型可用的工具清单常见的有read_file、write_file、list_dir、glob、grep、bash等。每个工具都有一段JSON Schema描述告诉模型“你能干什么、参数是什么格式”。这里有一个很实际的经验模型每轮请求都会把这堆工具定义塞进上下文工具越多token消耗越大模型“选错工具”的概率也越高。所以我个人会通过配置文件裁掉不常用的工具只保留读写文件、搜索、执行命令这几类。别小看这一步裁完以后同量级任务的响应速度能明显提升尤其在用小参数模型的时候。bash工具是最强也是最需要警惕的一个。它相当于给模型开了一个终端几乎什么都能干也意味着一旦权限管控没做好一个“顺手”的rm -rf就能让你欲哭无泪。建议在opencode.json里通过permissions.allow和permissions.deny把所有高风险操作挡在门外比如{ permissions: { allow: [ bash:git*, bash:ls*, bash:cat*, bash:grep*, bash:find*, read:*, write:src/** ], deny: [ bash:rm*, bash:sudo*, bash:curl*, bash:wget* ] } }这样设置之后模型想执行sudo apt install或直接下载远程脚本的时候会被拦下来得经过你确认。别嫌麻烦这是把Agent请进工作流的底线安全措施。另外提醒一点read_file对大文件有截断行为读那种几千行的文件时只返回开头和结尾需要配合grep精准定位而不是让模型一次性“吞”整个文件。1.2 Skill把固定套路封装成提示词工具解决的是“能做”而Skill解决的是“做得符合我的习惯”。opencode里可以通过.opencode/skills/目录创建自定义Skill本质是用一整套带前置条件的提示词模板把高频重复的工作流固化下来。举个例子我经常让opencode帮我把代码改动整理成规范的中文提交信息以前每次都要在对话里翻来覆去描述“按什么格式、包括哪几个部分”后来写成postcommit.md这个Skill一个问题就能触发。形式很简单一个带YAML frontmatter的Markdown文件--- name: postcommit description: 将当前改动整理成符合项目规范的提交信息 triggers: - 提交 - commit - 提交说明 --- 请执行以下步骤 1. 使用 git diff --stat 查看本次改动范围。 2. 使用 git diff 查看具体改动内容忽略第三方库目录。 3. 根据改动的类型生成一份包含“影响范围”“关键改动”“测试建议”三部分的提交信息。 4. 输出提交信息时标题不超过50字正文逐条列出。把这种Skill放在项目根目录的.opencode/skills/下团队所有人都能共享。写Skill的核心原则是把“思考”留给模型把“规则”写进模板。越是细节化、项目化的规则越应该沉淀成Skill而不是每次重新描述。我见过不少团队用Skill统一了代码审查的检查点、数据库迁移脚本的编写规范甚至新需求的技术方案文档生成流程。这套机制的聪明之处在于它不需要改一行代码纯粹的“提示词工程”但带来的工作流一致性非常明显。还有一类Skill适合做成全局的放在用户级配置目录下比如~/.config/opencode/skills/。我自己的全局Skill里就有一个explain_large_function遇到超长函数时要求模型按调用链分层输出说明配合条件触发词“长函数”。这比每次手动组织语言稳定得多。1.3 MCP接入外接服务时的三个教训MCPModel Context Protocol是opencode接入外部服务的方式相当于给模型接了一个“应用商店”。通过opencode mcp add可以连上本地数据库、内部API文档、GitHub仓库、Jira等。形式上是标准化的MCP Server只要对方实现了协议opencode这边就能直接注册工具调用。这里要把我踩过的坑直接摊开说。第一MCP不是越多越好。每多注册一个MCP Server模型在每轮请求里都得多考虑一批“可用的工具”。我试过同时挂5个MCP Server结果模型在简单问题上开始频繁“手滑”调错工具、传错参数响应时间也肉眼可见地变慢。现在我的原则是“同时不超过3个”用不上的立刻opencode mcp remove。第二MCP Server的稳定性直接决定你的体验。很多MCP Server是被封装成本地进程或远程HTTP服务的进程崩溃、端口被占、token过期各种问题都可能导致Agent卡死在工具调用上。opencode提供了opencode mcp list查看状态遇到异常先重启对应服务再看。另外自己写MCP Server时一定要保证所有分支都返回结构化结果别把异常堆栈裸抛出来否则模型会陷入反复重试同一个工具的循环。第三接入MCP前先问一句“这个能力能不能用普通文件或命令行替代”。比如查内部API文档如果只是少量信息完全可以在Skill里写一个读取本地MD文档的步骤没必要额外引入一个服务。MCP的价值在于“动态数据”比如查实时订单状态、操作在线工单如果仅仅是静态资料用文件就是最便宜、最稳定的方式。2. 服务面让opencode从“聊天框”变成“后端引擎”2.1 三种形态交互、一次性执行、常驻服务opencode的“服务面”是我最看重的一部分。它本身是一套CLI但交互式TUI只是其中一种形态。实际工作流里我大量使用另外两种形态一次性执行和常驻服务。一次性执行的基本形式是opencode run 你的指令。这个命令不会进入交互界面而是启动一个Agent进程执行完任务后直接退出。这一条被我用在脚本里用得非常多比如配合git hook在提交时自动做增量代码检查或者通过cron定时跑一个“清理临时文件”的任务。因为是独立的进程天然适合被其他程序调用不用担心污染正在进行的交互会话。常驻服务对应的命令是opencode serve。它会启动一个HTTP服务把Agent能力暴露成API。配置--port和--hostname即可通常我建议绑到127.0.0.1避免暴露到局域网。开了serve之后你可以写一个简单的Python或Node脚本用HTTP请求把任务丢给opencode执行然后轮询结果。这非常适合“异步代跑”你在IDE里写代码写了一段测试框架但懒得手动跑直接把请求丢给常驻服务让它分析、执行、返回报告。选择建议很直接只想和AI对话、看它改代码用交互式TUI要接入自动化流水线用run需要同时服务多个上游任务、或者要给自研工具做AI后端用serve。三种形态在底层共享会话和工具定义切换成本很低。2.2 Provider配置与免费额度那些坑opencode支持多个模型提供商并允许在同一个会话里按任务切换。基础配置通过opencode auth登录或者在配置文件里指定模型路由。我第一次配置时用的是Anthropic的模型后来因为成本和响应速度的考量把DeepSeek、本地Ollama模型也加进来形成了一套“按任务类型分模型”的规则。配置文件里可以通过models数组定义多条规则比如{ models: [ { name: cloud, model: anthropic/claude-sonnet-4-20250514, provider: anthropic }, { name: fast, model: deepseek/deepseek-chat, provider: deepseek }, { name: local, model: ollama/qwen2.5-coder:14b, provider: ollama } ] }这样在TUI里按/model fast就能切到快而便宜的模型处理机械改动切到cloud做架构级重构。切模型的核心原则是“低成本模型负责执行高成本模型负责思考”别用杀鸡刀宰牛也别让牛刀去干杀鸡的活。免费额度是另一个高频被问的话题。opencode的console provider集成了一个free tier官方的设计意图是让用户体验完整能力。但这个免费档位有一个非常扎眼的限制只能从opencode官方CLI发起调用。如果尝试通过第三方客户端、自建OpenAI兼容端点去复用这个额度服务端会直接返回类似opencodes free tier can only be used from within opencode的错误。这不是什么绕过不了的障碍而是它本来就不允许外部复用。我的建议是别在这上面花时间折腾免费额度当作体验就好真实项目还是配正式API。2.3 服务化场景异步任务与规则化调用把opencode真正当“服务”使用之后我摸索出的一个稳定模式是异步任务 回调结果。原理不复杂你通过HTTP API创建一个任务opencode在后台跑完成后把输出写到指定文件或回调地址。整个过程不需要一直盯着终端。我自己的一个落地案例是“PR描述生成器”。公司在GitLab上提PR时需要描述改动背景、影响模块、测试建议。以前靠人写现在用一段小脚本在push之后调用opencode让它读取MR source分支与目标分支的diff按照团队规范生成PR描述再通过GitLab API自动填入。这个任务放在常驻服务上跑一个人提交代码团队其他人都能受益。服务化之后还有个细节值得注意请求参数最好显式指定max_turns和超时时间。max_turns限制模型最大思维链轮数防止它在一个简单任务上无限“思考—工具调用—再思考”下去。设计服务接口的时候我会在请求体里强制带上这些参数宁可任务失败返回错误也好过无休止地消耗token。3. 外壳终端里的体验工程3.1 TUI操作与快捷键盘点opencode的交互式TUI是很多人第一次接触它的入口但大多数人都没把它用透。说几个我每天都在用的操作/model切换模型、/new开启新会话、/compact压缩上下文、/cost查看当前会话花费。这些斜杠命令比鼠标点击高效太多尤其是/compact。长会话里上下文越来越笨重模型会开始丢掉早期信息甚至重复读取同一个文件这时候一条/compact能显著“提神”。会话恢复也是个隐藏很深的效率点。opencode sessions可以列出历史会话配合--continue参数能直接接续上一次的聊天特别适合跨天处理同一个功能分支的场景。几点半下班时中断的工作第二天一杯咖啡的功夫接着聊。如果你习惯多任务并行我推荐tmux里开多个pane每个pane跑一个opencode会话。这块看起来和opencode本身无关但实际体验提升巨大一个会话在跑数据库迁移检查另一个在处理前端样式调整各不干扰。Linux下配合tmux的session保存功能重启机器后所有的会话还能原样恢复。TUI里的输出长度也是个痛点。模型回答动不动就几百行翻滚查找很痛苦。opencode支持把回答保存到文件的命令在“需要完整结果但不想刷屏”的场景下我会直接让它把结果写进临时文件再用编辑器打开阅读体验好得多。3.2 VSCode与opencode联合作战虽然opencode本身是终端工具但现代开发基本离不开VSCode两者完全可以协作起来而不是对立。我常用的方式是在VSCode内置终端里跑opencode代码写在编辑器左侧Agent在右侧终端里操作文件。需要让它看某个具体文件时直接在对话里说“读取src/utils/parser.ts”它就能用工具精准定位。用内置终端的一个额外好处是VSCode的“打开文件于编辑器”快捷键可以直接从终端跳到编辑器快速查看Agent修改过的文件。我通常让Agent改完代码后自动git diff然后在终端里把差异渲染出来确认没问题后切到编辑器继续改整个流程平滑得不像话。还有一个小技巧通过管道把外部命令结果喂给opencode。比如先用rg -l TODO找出所有含待办标记的文件列表再把这个列表通过opencode run 分析这些文件的TODO内容并分类传给Agent。这样能避免把整个仓库的无关文件都塞进上下文模型拿到的始终是“筛选过的精华”。这也是我对“上下文工程”最基本的理解喂给模型什么比你让它干什么有时候更重要。3.3 精调配置文件与环境变量opencode的主配置是opencode.json可以放在项目根目录做团队级配置也可以放在用户目录当个人默认配置。这个文件支持定义模型路由、权限、界面主题、快捷键等。环境变量则用来存放不该写进文件的敏感内容和运行时参数比如OPENCODE_CONFIG指定配置文件路径OPENCODE_LOG_LEVEL控制日志级别。一个团队级配置的最小示例{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, theme: dark, permissions: { deny: [bash:git push*, bash:rm -rf*] } }放在项目根目录后所有团队成员拉下来仓库就能得到一致的模型默认值和安全策略。但有两点必须注意第一不要把API Key写在这个文件里用环境变量引用第二别把过于苛刻的权限配置写进团队级文件否则成员会频繁遭遇工具调用失败最后选择绕开它自己手动操作反而更危险。我个人习惯把OPENCODE_LOG_LEVEL设为debug只用在出问题时平时保持默认即可。日志默认落在本地目录排查Agent“神秘行为”时打开看一眼往往能发现是工具调用超时还是某个shell命令的退出码被忽略。4. 实战集成把AI编码代理塞进工作流4.1 个人工作流四段式会话法用了opencode一段时间后我逐渐形成了一套“四段式会话法”的个人工作流算是把“一个对话干到底”的坏习惯改掉了。四段分别是需求拆解、方案设计、编码执行、复盘总结。做新功能时我会先开一个会话A只让它读需求文档和相关代码输出理解和拆解绝不写代码。这个阶段的核心是“对齐信息”防止后面越做越偏。然后开会话B基于前面的拆解做设计方案涉及表结构、接口定义、时序变化。会话C才真正动手改代码把设计方案的结论作为输入逐模块实现。最后会话D用来做代码审视让Agent对照设计方案检查实现是否遗漏。每开新会话我都会把上一个会话的结论用文字粘过去。这看起来有点原始但效果远比“一个会话从头聊到尾”好因为每个阶段的上下文都非常聚焦模型不会被无关信息干扰。这套方法本质上是把人类的“阶段性交付物”概念搬到Agent协作里每个会话都有目标、有产出、有验收标准。4.2 团队落地统一配置、代码审查钩子与CI把opencode从个人工具变成团队基础设施需要解决三个问题配置一致性、安全边界、自动化接入。配置一致性最简单把带权限和模型规则的opencode.json提交到仓库根目录。安全边界要靠环境变量管理密钥再加上权限白名单。自动化接入则是把它塞进现有CI/CD和Git钩子。我落地的一个案例是“pre-push钩子里做增量代码审查”在.git/hooks/pre-push里写一段shell对比要推送的分支和远程目标分支调用opencode run 按团队规范审查以下diff...把审查结果输出到终端。质量不过关就中断push。这个钩子写得简单一个示意片段#!/bin/sh branch$(git rev-parse --abbrev-ref HEAD) targetmaster if [ $branch ! $target ]; then diff$(git diff --stat $target...$branch) if [ -n $diff ]; then echo Running opencode review... git diff $target...$branch | \ opencode run 请审查上述diff重点关注错误处理、日志规范、潜在bug。输出问题列表并按严重程度排序。 fi fi注意这条命令里的opencode run用的是免费额度也可能足够但团队正式使用建议配置共享的API Key否则每个人都要单独登录。CI里的用法类似在GitHub Actions中增加一个jobcheckout代码后调用opencode做定点检查。核心思路是“把Agent当成一个可以通过命令行调用的同事”只要能命令行调用就能接入一切自动化框架。4.3 性能、安全与成本的三重平衡实战集成绕不开一个三角权衡性能、安全、成本。想跑得快模型要强那成本就高安全管得严每次工具调用都人工确认那流程就慢。我处理这个矛盾的方式是“分区域设置不同策略”。在开发本地权限可以放宽为了让Agent顺畅地读文件、跑测试确认频率尽量低。在共享CI环境权限收紧禁止执行push以外的一切可能产生副作用的命令同时限制只能操作临时目录。在涉及生产数据的任务里我会直接不给它访问权限让脚本在外部完成数据脱敏后再交给Agent处理。成本控制的另一招是“用小模型做预筛”。比如要做全仓库的代码风格检查先用14B的小模型跑一遍把疑似问题标记出来再用强模型只审核被标记的部分。这比让强模型从头到尾扫一遍便宜得多效果还更可控。opencode支持模型路由我可以把一个任务拆两步分别指定不同模型把成本压到原来的三分之一左右。5. 常见问题与排查心得症状可能原因解决办法报错free tier can only be used from within opencode尝试在非官方CLI环境调用console免费额度只在原版opencode里使用或者直接配置正式APIAgent反复执行同一个工具调用却不进展工具返回结构异常或MCP Server故障opencode mcp list查状态重启服务给任务设置max_turns上限模型漏掉上下文里的关键约定会话太长早期信息被截断或忽略使用/compact压缩或者开新会话把约定重新写入修改文件时权限被拦permissions配置过严调整allow/deny列表并明确是“全局拒绝”还是“仅提醒”bash工具执行结果为空命令路径或环境变量不一致在配置里指定shell环境或者改用绝对路径执行TUI输出中文乱码终端编码不是UTF-8Windows下执行chcp 65001后重开终端本地缓存占满磁盘历史会话和日志累积定期清理.cache/opencode下的session和log文件排错的心态也很重要。Agent经常会被当成“黑盒”一出问题就开始猜。我的做法是先看日志再看工具调用记录最后复现一次。日志里能看到模型每轮选了什么工具、传了什么参数、拿到什么结果。绝大多数问题都不是模型“笨”而是上游条件没满足——目录不存在、另一套命令还没执行、权限被系统拒绝。沿着这个思路去排查往往一两分钟就能找到根因。另外窗口期的小毛病别急着换工具链。opencode的安装和使用都算简单遇到报错先查版本、查配置很多时候是升级之后配置格式变了。它的社区和文档都在快速迭代保持“工具是辅助工作流才是核心”的心态比纠结某一个版本的某个bug有意义得多。最后分享一点实实在在的个人体会。我最初接触opencode时也走过弯路又是折腾免费额度又是试图接一大堆MCP最后发现真正让效率提升的反而是把基础工具吃透把工作流掰顺。它最有价值的地方在于把“看代码、搜文档、改文件、跑命令”这几件原本分散的事全部收拢到终端里由Agent串成一条线。工具链越简单出错的环节就越少整套系统就越稳。如果再让我给新用户一个建议那就是先别急着追求“全都要”从日常一两个重复性动作做起让它替你跑顺再慢慢往深处走。