opencode 这个项目我从 0.2.x 版本开始盯到现在说句实话它越来越不像一个“终端里的聊天框”更像一个可以自由插拔的 Agent 运行时。上篇把安装、启动和基本会话聊得差不多了后台留言里问得最集中的是后面这几个事工具权限怎么开才不烦人Skill 到底是个什么东西opencode go 的免费额度为什么老是报错以及能不能把它塞进 VSCode 和现有的 AI 工作流。这篇就顺着工具、服务面、外壳、实战集成这条线一次聊透适合已经跑起来但想真正用进日常项目的人。文里所有操作都是我实际跑过的你照着来基本不会踩到我踩过的坑。1. 先搞清楚opencode 到底是一套什么东西1.1 它不是“又一个 Claude Code 换皮”可能有人觉得 opencode 就是开源版的 Claude Code我一开始也这么想但用一段时间之后发现它俩的产品定位不太一样。Claude Code 是 Anthropic 做好的一个完整产品交互、权限、工具链都按它自己的逻辑来opencode 更接近“开放协议的 Agent 运行时”把模型、工具、权限、会话存储拆成可以替换的模块。这种差异最直观的体现是你可以在同一个项目里换模型、换工具集、换渲染模式业务代码不用动。我自己的日常用法是在同一个仓库里维护两个 profile一个走官方托管服务做探索性重构一个走本地模型做私有代码分析。两个 profile 共用同一套 Skill只有模型和权限不同。如果只是“换皮”做不到这种灵活度。1.2 配置驱动的核心设计opencode 的行为几乎全部由配置驱动。项目根目录放opencode.json用户级配置放~/.config/opencode/opencode.json你还可以用环境变量覆盖其中一部分字段。这个设计的价值在于整套 Agent 行为可以放进 git 仓库团队其他人 clone 下来之后跑出来的效果尽可能一致。但它也有代价。opencode 迭代快配置字段时不时会调整跨大版本直接复用旧配置经常出问题。加上文档散落在各个地方新手很容易配出一个“看起来能用、用起来抽风”的组合。第 4 节我会把配置的覆盖关系单独讲清楚这里先记住一个判断标准凡是和密钥相关的走环境变量凡是和项目行为相关的走项目配置默认兜底才放全局。再说会话存储。opencode 默认把会话数据放在用户目录下而不是跟着项目走。好处是换目录还能恢复历史坏处是团队没法共享聊天记录谁需要谁自己导出。这个特性一开始容易被忽略等你开始用脚本批量跑任务的时候就会意识到会话归档有多重要。2. 工具面内置工具、权限边界与 Skill 机制2.1 opencode 的内置工具清单里哪些该放开、哪些该收紧opencode 内置工具大致分几类文件读写、命令执行、搜索、子任务。最常见的包括read、write、edit、glob、list、grep、bash以及用于并行处理复杂任务的task。我按实操体会给一张权限建议表工具典型用途权限建议read / glob / list快速了解代码结构放开grep全局搜索关键字放开write / edit修改文件内容允许指定目录如 src/、tests/bash执行命令白名单模式谨慎放开task并行子任务放开但限制数量为什么这么配因为 opencode 的价值在于它真的会动手改代码而风险也恰恰在这里。read这类只读工具放开没有问题edit和write一旦误操作至少会污染当前工作区。bash更危险一个没写对的rm就可能把环境搞坏我早期就因为这个回滚过两次代码。2.2 权限策略怎么配才不烦人权限策略我踩过两个极端。一开始全部默认每个命令都弹确认五分钟之内我就烦了后来干脆全放行结果它在没注意的时候改了一堆文件回滚花了我半小时。现在的做法是edit和write允许项目目录内操作bash用白名单放行安全命令比如git status、git diff、npm test、yarn lint这类不会造成破坏的操作白名单外的命令每次询问。配置里大概长这样示意{ permission: { edit: allow, bash: { allow: [git status, git diff, npm test] } } }注意白名单只是“默认放行”的意思不等于它不能跑其他命令只是每次会多一次确认。真正要堵死的是那些确认了也不能让它跑的命令建议显式放进deny列表比如rm -rf、sudo相关的危险操作。别指望默认设置帮你兜底安全边界得自己画。2.3 Skill 的本质是一袋子文件很多人把 Skill 想得很玄其实它就是一组“给模型看的说明 可选脚本/模板”的目录。核心文件是SKILL.md里面写清楚这个 Skill 什么时候用、怎么用、有哪些约束。模型读到之后会在合适场景主动调用而不是等你一条条手动触发。Skill 跟“提示词模板”最大的区别是它可以携带脚本和文件模板。比如代码评审 Skill 可以带一个rules.md里面是团队规范发布检查 Skill 可以带一个脚本跑一遍依赖检查。这让 Skill 不只是“说话”而是“干活”。我做过最舒服的一件事是把团队 Code Review 的检查项全部沉淀进一个 Skill后续每个新成员上手时Agent 自动就能按同样的标准做初检。2.4 手把手搭一个可用的 Skill搭建流程不复杂但细节决定成败。第一步在.opencode/skills/skill-name/下建目录。第二步写SKILL.md至少包含name、description、usage三段。第三步如果 Skill 需要执行脚本把脚本放同目录并在SKILL.md里写清楚执行方式。第四步重新打开会话通过 Skill 列表确认加载成功。第五步用一个真实任务测试比如“用发布检查 Skill 检查当前分支”。这里面最容易被低估的是description。它要写得像搜索引擎的索引说清楚适用场景而不是泛泛地写“帮助检查代码”。模型是靠 description 决定何时调用 Skill 的描述越精准调用越及时。我测试过同一个 Skill把描述从“用于检查代码”改成“用于检查发布前的依赖、测试和 git 状态适合在提 PR 或打 tag 前调用”整体触发率明显提升。2.5 工具面的三个隐蔽坑第一个坑是环境变量不一定会透传到bash工具里。opencode 执行命令时用的是非交互 shell.bashrc里定义的别名和变量可能读不到。解决办法是写绝对路径或把需要的变量写进 opencode 配置的环境变量段别指望 shell 配置自动继承。第二个坑是工具之间没有共享“工作内存”。一次会话里模型通过read拿到的内容不会自动同步给另一个子任务工具。设计 Skill 时尽量把所需上下文写进 prompt 或脚本参数里不要指望工具帮你记住上一轮的细节。第三个坑是超大仓库里grep会慢。大项目里全库搜索经常超时建议把不必要的目录加进 ignore 列表或者用精确路径缩小范围。我接手过一个巨型 monorepo默认配置下搜索动不动就卡住后来把node_modules、构建目录全部 ignore 之后才顺畅起来。3. 服务面模型供应商、opencode go 与免费层3.1 多供应商配置其实是一张路由表opencode 支持多家模型供应商你可以在配置里指定哪个模型用于哪个场景。它的思路很直接配置里声明 provider然后 model 字段指向具体模型 ID。我常用的组合是一个托管模型做日常问答和重构一个本地模型做离线场景两个模型用同一个 opencode 配置只是启动时用不同 profile。这比在别的工具里来回改环境变量舒服得多。以前我用某些编辑器插件时切换模型要打开设置面板改字段改完还得重启opencode 这边只要把 profile 指针动一下或者用环境变量指定 provider剩下的活交给启动流程就好。特别是配合 shell alias切换成本低到可以忽略。3.2 opencode go 和本地 key 的区别opencode go 是官方提供的托管服务你可以理解成“官方把模型 API 和 opencode 会话服务打包在一起”。本地 key 是你自己拿模型平台的密钥在 opencode 里直接配。两者的区别主要在便利性和控制权。opencode go 上手快不用自己管理多个 key额度也统一本地 key 则更可控费用透明方便复用已有账号。我的建议是日常体验先用官方 go 的免费层跑通流程等深入使用后按需切回本地 key。别一上来就买大额套餐先用免费层摸清自己的调用频率再说。3.3 “free tier can only be used from within opencode” 到底在说什么这是很多人问的一个报错完整信息长这样error from provider (console): opencodes free tier can only be used from within opencode。翻译成人话你把 opencode go 的免费额度拿去当通用 API 转发了。opencode go 的免费层只允许在官方 opencode 客户端会话里使用如果你把它的端点地址填进别的工具或者做了代理转发服务端校验请求来源之后就会拒绝。这个限制不是 bug是策略目的就是防止免费额度被薅成通用 API。解决方式有三条第一条直接使用官方客户端别做转发第二条升级到付费套餐开通 API 转发能力第三条换成本地 key自己接供应商。我个人建议先确认自己是不是真的需要转发很多场景下直接用 opencode 客户端就够了折腾转发反而引入额外的不稳定因素。3.4 套餐额度按模型分开算吗热词榜里有个问题问得很细opencode go 套餐“每种模型分开计算额度吗”。从我实际使用的经验看这类托管服务的额度计算大体分两种按账号维度统一扣减或按模型维度分别扣减。opencode go 具体属于哪种建议以账户面板或官方文档为准不要听二手消息。排查方法很简单打开套餐详情页看有没有按模型分类的用量表如果没有就连续用同一个模型跑几次请求观察余额变化是否只和总请求量挂钩。用量数据是最诚实的别凭感觉判断。另外一个实用习惯是每个月固定做一次用量截图存档后面核对账单时心里有底。3.5 用 cc-switch 管好多套配置cc-switch 是社区里用来管理 Claude Code、Codex 等工具配置的小工具核心能力是保存多套 API 端点、模型、密钥组合一键切换。opencode 也可以配合使用尤其是你同时维护个人账号、团队账号、不同供应商配置时这玩意儿能省不少事。我的用法是给每套环境建一个配置模板cc-switch 负责往环境变量或配置目录写入当前选中的那套。切换供应商时不需要手改opencode.json误操作概率低很多。要注意cc-switch 的切换本质是改配置切换后最好新开一个 opencode 会话避免旧会话拿着旧配置继续跑。不然你会在排查问题时遇到“配置明明改了行为却没变”的尴尬情况。4. 外壳面终端交互、配置层级与 Zen 模式4.1 从全屏 TUI 到极简输出的三种状态opencode 的“外壳”体验比大部分终端工具讲究。它不只有一个全屏 TUI还支持紧凑输出和 Zen 模式。全屏模式适合集中思考信息密度高紧凑模式适合在普通终端里看输出不占满屏幕Zen 模式则把干扰降到最低只保留必要信息对深度专注很有帮助。我写代码时常用全屏跑批量任务时用非交互模式。Zen 模式反而在演示和录屏时用得多观众注意力不会被密集的 UI 分散。三种状态切换很快不需要改配置习惯之后你会很自然地在写代码和看结果之间切换不会有“工具感”。4.2 配置文件的三层覆盖关系opencode 的配置有三层全局配置、项目配置、环境变量。优先级从低到高大致是全局 项目 环境变量。这意味着你可以把“默认用哪个模型”放在全局把“这个项目只能用只读权限”放在项目配置把“今天临时换个大模型跑分析”用环境变量传入。我见过不止一次这种事开发者在编辑器里把 provider 密钥写进项目配置然后整个目录提交到 git这是最典型的翻车现场。密钥和敏感信息尽量走环境变量项目配置只写非敏感的行为字段。你也不想哪次开源项目分享时把自己的密钥打包发给全世界。4.3 脚本化调用 opencodeopencode 可以用非交互模式跑一次性任务比如opencode run 帮我检查这个 PR 的变更文件。这个能力让它可以进 CI、进 pre-commit 钩子、进批处理脚本不再只是一个人自嗨的工具。脚本化要注意两点。第一给足上下文非交互模式没有 TUI 里的多轮对话一次 prompt 里的信息越完整结果越靠谱。我习惯把相关文件路径、期望的输出格式全部写进 prompt跑出来的内容基本能直接用。第二注意超时设置长任务容易被外部超时机制杀掉给 CLI 预留充分的时间预算别在 CI 里设一个 30 秒的硬超时然后抱怨它跑不完。4.4 把 opencode 放进日常 shell 流程我常用的技巧是给 opencode 设置一个短别名比如oc。另外把常用提示词写成 shell 函数例如对刚才git diff的文件做一次快速 review一个函数就能完成“取变更列表 → 传给 opencode → 输出评审意见”的流程。这种组合让 opencode 不再是需要单独打开的“另一个工具”而是 shell 里顺手就能用的能力。提示把这类函数放进 dotfiles 仓库后换机器五分钟就能重建完整工作流。我因为这个习惯省下了大量重复配置时间。5. 实战集成编辑器、团队与模型选型5.1 VSCode 里怎么跟 opencode 协作opencode 有 VSCode 扩展装上之后可以在编辑器侧栏直接开会话。我的习惯是编辑器主窗口写代码侧栏跑 opencode 做重构和错误分析这样上下文不用来回切换眼睛也不用在多个窗口之间跳。如果你更习惯终端也可以在 VSCode 的集成终端里跑 opencode TUI。两者不冲突选一种当主入口就好。唯一要注意的是别同时开两个会话改同一批文件Agent 写文件和你手动编辑撞车时冲突解决起来很头疼。我后来在项目配置里把 Agent 的edit权限限定到src/目录至少把撞车范围控制住。5.2 把 Skill 从 opencode 带到其他 Agent 工作流经常有人问opencode 里调通的 Skill 能不能给 Claude Code 或其他 Agent 用。可以迁移但不要指望直接搬运目录就能生效。不同 Agent 对 Skill 的加载规则、文件命名要求不完全一样硬搬过去大概率静默失效。我的做法是保留 Skill 的核心逻辑和脚本重写一份目标环境需要的说明文件。核心资产是逻辑不是格式。像 cc-switch 这类工具只能帮你切配置不能替代 Skill 的语法适配。想通这一点之后你再面对“A 工具迁移到 B 工具”的诉求时就不会慌因为你知道真正要迁移的是哪一部分。5.3 DeepSeek、Hermes 这类模型怎么选热词里有“opencode 与 deepseek hermes 哪个好”这个问法其实不成立。DeepSeek 是一整套模型服务Hermes 是某个模型家族里的系列权重opencode 只是一个 Agent 运行时。真正要选的是“在 opencode 里跑哪个模型来完成什么任务”。从我的实际体感说日常重构和代码生成用托管模型体验更顺尤其是工具调用稳定本地部署 Hermes 系列适合对数据敏感的场景胜在可控。如果模型工具调用老是失败先检查它是否支持 function calling再检查 prompt 里工具说明是否太长被截断。有些模型上下文窗口有限工具列表一长后面的说明就会被裁掉表现就是“不听话”。5.4 团队共享 skill 仓库的一个可落地做法如果团队想统一 Agent 行为一个可落地的方案是建一个skills仓库用 git submodule 或者脚本同步到各项目的.opencode/skills目录。仓库里每个 Skill 配一个 README 和测试命令更新时跑一遍冒烟测试确认没有破坏现有调用。我踩过的坑是Skill 里写死绝对路径。换机器后路径不对整个 Skill 直接失效。建议所有 Skill 都基于项目根目录的相对路径并在SKILL.md里说明前置条件。另外团队 Skill 仓库里最好放一个CHANGELOG.md每次变更把行为差异写清楚否则你三个月后回看根本不知道某个 skill 为什么突然变了。6. 常见问题与排查技巧实录6.1 Ubuntu 安装后找不到命令Ubuntu 上装 opencode 最常见的坑是 Node 版本太老。opencode 依赖较新的 Node 特性如果 nvm 没切到目标版本安装脚本执行成功但命令跑不起来。我建议先确认node -v再安装。另外装完后如果opencode命令找不到检查安装路径是否在 PATH 里特别是用官方脚本装到用户目录的情况。重新登录一下终端或者手动 export 路径通常能解决。别一上来就怀疑安装脚本坏了先把环境基础打牢。6.2 会话历史丢失opencode 的会话存储默认在用户目录下换机器后如果没同步配置文件看起来就像历史丢了。排查顺序是先确认会话存储目录有没有数据再确认当前项目用的是不是同一份全局配置。我实际遇到过一次升级版本后旧会话打不开原因就是存储格式变了。所以重要会话建议导出存档别只依赖本地存储。平时可以把关键会话归档成 Markdown 或者截图既方便回顾也方便分享给团队。6.3 同一个请求在不同模型上结果差很多这不是 bug。不同模型的工具调用风格、上下文窗口、指令遵循能力差异很大。遇到这类问题先别急着怀疑 opencode先做对比实验同样的 prompt 在同一个模型下跑两次看是否稳定。稳定说明是模型差异而不是配置问题。优化方向有两个一个是精简 prompt减少与任务无关的背景信息另一个是给模型足够的工具说明让它在合适时机调用而不是凭空猜测。模型不是你肚子里的蛔虫prompt 写得不清楚再好的模型也发挥不出来。6.4 常见问题速查表现象可能原因处理方式安装后命令不存在Node 版本过低或 PATH 没配升级 Node确认安装路径free tier 报错把免费额度当 API 转发用官方客户端或升级付费套餐Skill 不生效SKILL.md 描述不清晰重写 description明确触发场景bash 工具读不到别名非交互 shell 不加载 rc用绝对路径或配置环境变量模型工具调用失败模型不支持 function calling换支持工具调用的模型跨版本配置报错配置字段变更查看更新日志调整字段我自己的实际感受是把 opencode 真正用进日常工作最有价值的不是某一个具体模型而是“工具 权限 Skill”这套可复制的框架。踩过几次坑之后我现在每接一个新项目都会先把 Skill 和权限配置写好然后让 opencode 在规则明确的范围内干活。最后再分享一个小技巧如果你是团队里第一个引入 opencode 的人不要一上来就铺开全套自动化先从最简单的 code review Skill 开始让大家先感受到价值再逐步扩展到自动测试、发布检查这些场景推广阻力会小很多。