1. 从零跑通 opencode为什么我建议你先搞懂 opencode.json 与 Agent 协作opencode 是一个跑在终端里的 AI 编码助手能读你的项目、改你的代码、执行命令适合习惯命令行、又想让 AI 深度参与开发流程的人。它和普通聊天式工具最大的区别在于opencode 把「模型」「智能体Agent」「技能skill」拆成了可配置的模块而这一切的入口就是opencode.json。你可以把它理解成一份「团队花名册」——谁负责出方案、谁负责写代码、谁负责审查各自用什么模型、什么温度、什么权限全写在这份文件里。很多人第一次装完 opencode直接开一个会话就开始问问题结果发现 AI 一会儿很保守、一会儿又乱改文件上下文越聊越乱。问题不在模型而在于你没有把 Agent 分工配好。我实测下来只要把opencode.json里的 Agent 定义、skill-creator 生成的技能、以及 oh my opencode 的工作流串起来同一套模型能跑出完全不同的稳定度。这篇内容聚焦三件事第一用opencode.json定义 plan / build / creative 这类 Agent第二用 skill-creator 生成可复用技能并放进 skills 目录第三用 oh my opencode 把多智能体协作串成一条可复用的流程。每一步我都会给出可直接复制的配置片段、目录结构和验证命令你照着敲就能在本地跑通。适合已经装好 opencode、想从「能用」进阶到「好用」的开发者也适合被上下文爆炸折磨过的朋友。2. 前置准备opencode 安装、oh my opencode 与模型接入的完整配置在动opencode.json之前得先把底座搭好。opencode 本体、oh my opencode 插件、以及一个可用的模型通道三者缺一不可。这一节我按「装什么 → 放哪里 → 怎么验证」的顺序讲避免你装完不知道文件去哪了。先说 opencode 本体。安装方式按你系统选装完后终端里执行opencode --version能打印版本号就说明二进制没问题。接着是 oh my opencode它是一个增强插件装完后会在配置目录生成oh-my-opencode.json。验证命令是cat ~/.config/opencode/oh-my-opencode.json如果能看到 JSON 内容哪怕只是默认结构说明插件已就位。Windows 用户注意路径是C:\Users\你的用户名\.config\opencode\别在 PowerShell 里用~混着写容易找不到文件。然后是模型接入。opencode 支持多种提供商你在交互式配置里选提供商、填 API Key、选模型即可。这里有个关键点Base URL、API Key、Model ID 三件套必须成套出现缺一个就会在请求阶段报错。如果你用的是兼容 OpenAI 协议的中转服务Base URL 要填到/v1这一层Model ID 要和你实际调用的模型名完全一致大小写都别错。以 TaoToken 为例它的 API 地址是https://taotoken.net/api你在 opencode 的提供商配置里把 Base URL 指向它再填入在控制台生成的 Key模型名按你订阅的填。生成 Key 的入口在控制台接入细节可以对照官方文档API Key 管理https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc配完模型后先别急着配 Agent用一次最简单的对话验证通道是否通。在 opencode 里发一句「回复 ok」能正常返回就说明模型层没问题。这一步很重要因为后面 Agent 报错时你要能区分是「模型通道挂了」还是「Agent 配置写错了」。我踩过的坑就是Agent 一直报 401查了半天发现是 Key 复制时多了个空格。最后确认目录结构。opencode 的全局配置目录下通常会有opencode.json主配置、oh-my-opencode.json插件配置、skills/技能目录。如果skills目录不存在手动建一个mkdir -p ~/.config/opencode/skillsWindows 下就是C:\Users\你的用户名\.config\opencode\skills。这个目录后面放 skill-creator 生成的技能路径别搞错否则 opencode 扫不到。3. 可复制配置opencode.json 里定义 Agent、温度与 skill 目录这一节是核心直接给你能粘贴的opencode.json。先说清楚每个字段干什么再给完整片段。agent节点下每个键就是一个智能体的名字你可以自定义。description描述这个智能体的职责opencode 在需要调度时会参考它。temperature控制表达的发散程度数值越小越专一确定适合 plan 这种要严谨拆解任务的角色数值越大越有创造性适合写文案、想方案的 creative 角色。model指定这个 Agent 用哪个模型不写就继承全局默认。prompt可以塞一段系统提示词用来约束它的行为边界。下面是一份可直接复制的opencode.json我把它放在~/.config/opencode/opencode.json{ $schema: https://opencode.ai/config.json, model: your-default-model-id, agent: { plan: { description: 负责需求分析、方案设计与任务拆解不直接改代码, temperature: 0.1, prompt: 你是方案规划智能体。先输出实现思路与步骤清单确认后再交给 build 执行。禁止直接修改文件。 }, build: { description: 负责按既定方案编写与修改代码执行命令并验证结果, temperature: 0.2, prompt: 你是编码执行智能体。严格按 plan 给出的步骤操作每步完成后说明改动了哪些文件。 }, creative: { description: 负责命名、文案、架构脑暴等需要发散的任务, temperature: 0.8 } }, skills: { paths: [ ~/.config/opencode/skills ] } }几个容易写错的地方。第一model字段填的是 Model ID不是提供商名字填错会在启动时报「model not found」。第二skills.paths里的路径Linux/macOS 用~没问题Windows 建议写绝对路径比如C:/Users/xxx/.config/opencode/skills用正斜杠更稳。第三JSON 不允许尾随逗号最后一个字段后面别加,这是新手最高频的语法错误。配好多 Agent 之后你在会话里可以用指定某个智能体干活比如plan 帮我拆解这个重构任务或者build 按上面的步骤改代码。为什么要多智能体协同因为 opencode 单次任务默认只用一个固定智能体而每个智能体的上下文是独立的。plan 负责想、build 负责做两者上下文隔离就不会出现「聊到后面 AI 忘了最初约束」的情况。这跟人类团队里「架构师」和「实现工程师」分工是一个道理。如果你还想让某个 Agent 用不同的模型比如 plan 用推理强的、creative 用便宜的就在对应 Agent 里加model字段覆盖全局。改完配置后重启 opencode 会话配置才会重新加载。4. skill-creator 技能生成与验证目录结构、安装命令与预期输出skill-creator 是 Anthropic 提供的一个技能作用是帮你「生成技能」。听起来有点绕简单说你告诉它你想让 opencode 具备什么能力它帮你产出一份符合规范的 skill 文件放进 skills 目录后opencode 就能在合适的时候调用这个技能。这比每次手写提示词高效得多。安装 skill-creator 最常用的方式是从 GitHub 拉npx skills add https://github.com/anthropics/skills --skill skill-creator执行后它会提示你把技能放到哪个目录选 opencode 的 skills 目录即可。如果你网络环境导致这条命令失败我遇到过卡在下载阶段的情况可以直接把 skill-creator 的文件夹手动复制到~/.config/opencode/skills/下面。目录结构应该是这样~/.config/opencode/skills/ └── skill-creator/ ├── SKILL.md └── (其他辅助文件)SKILL.md是技能的核心描述文件opencode 靠它判断「什么时候该用这个技能」。验证是否装好执行ls ~/.config/opencode/skills/skill-creator/SKILL.md能列出文件就说明路径对了。如果报「No such file」八成是你复制时多套了一层目录比如变成了skills/skill-creator/skill-creator/SKILL.md把内层挪出来即可。装好后在 opencode 会话里触发 skill-creator让它生成一个自定义技能。比如你想让 opencode 每次改完代码自动跑一遍 lint就可以描述这个需求skill-creator 会产出一份新的SKILL.md。生成的新技能同样放进skills/下的独立子目录重启会话后生效。这里有个实测经验skill 的description字段写得越具体opencode 触发它就越准。如果你写得太泛比如「帮助处理代码」它可能在不该触发的时候乱触发。建议写成「当用户要求对 TypeScript 文件执行 ESLint 并修复可自动修复的问题时使用」。另外skill 目录名和SKILL.md里的 name 保持一致能减少识别问题。验证技能是否被加载可以在会话里直接问 opencode「你现在有哪些可用技能」它会把扫描到的技能列出来。如果列表里没有你刚放的先检查路径再检查SKILL.md的格式是否符合规范通常是 YAML front matter Markdown 正文。5. 常见报错逐条排查401、local proxy failed、reading choices 与 OAuth配置过程中最容易卡住的不是写配置而是报错看不懂。这一节我把高频错误和对应排查路径列清楚你对着改就行。401 Unauthorized几乎都是 Key 的问题。先确认 Key 没有多余空格或换行再确认 Base URL 和 Key 属于同一个服务商。如果你用的是中转服务Base URL 要指向它而不是官方地址。还有一种情况是 Key 过期或被禁用去控制台重新生成一个。排查顺序Key 格式 → Base URL → 账户状态。local proxy failed / connection refused这类错误说明 opencode 连不上你配的地址。先ping或curl一下 Base URL 看通不通再检查是不是本地网络策略拦了。注意不要配置任何非法的网络转发工具正常的企业网络或家庭网络直连即可。如果地址写成了localhost但本地并没有起服务也会报这个。reading choices 相关报错通常出现在模型返回结构不符合预期时比如你用的模型不支持 OpenAI 的choices格式或者返回被截断。先确认 Model ID 填对再确认该模型是否兼容当前协议。有些模型需要特定的参数缺了就会返回空结构opencode 解析时就报 reading choices。OAuth 相关报错如果你选的是需要 OAuth 登录的提供商报错一般是 token 失效或回调失败。重新走一遍登录流程确认浏览器回调地址和终端提示一致。如果反复失败改用 API Key 方式接入更省事。Agent 不生效 / 不到检查opencode.json是否是合法 JSON可以用在线 JSON 校验器过一遍再确认 Agent 名字拼写和时一致。改完配置必须重启会话。skill 不触发检查skills.paths路径、SKILL.md是否存在、description 是否够具体。三者任一不对都会导致技能被忽略。排查时建议开一个最小复现只留一个 Agent、一个技能确认能跑通后再逐步加回。这样出问题时范围小定位快。另外opencode 的日志会打印请求详情遇到看不懂的报错先翻日志比盲猜高效。6. 把流程串起来oh my opencode 工作流与长期使用建议前面几节把零件都备齐了这一节讲怎么串成一条稳定流程。oh my opencode 的价值在于把「规划 → 执行 → 验证」变成可复用的工作流而不是每次手动 来 去。我的做法是接到一个任务先用plan让它输出方案和步骤清单确认没问题后用build按清单执行。执行过程中如果遇到需要发散的点比如起变量名、想接口设计切到creative。因为每个 Agent 上下文独立plan 的规划不会被 build 的调试细节污染build 也不会被 creative 的发散带偏。这就是多智能体协同最实际的好处。如果你要长期跑编码任务或 Agent 流程建议关注 Coding Plan 这类订阅方案成本比按量调用更可控Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想先验证模型效果、对比不同模型的表现可以直接在模型对话里试模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel几个长期使用的小技巧。第一把常用的 skill 沉淀下来别每次重写提示词skill-creator 生成一次就能反复用。第二Agent 的 temperature 按任务类型调plan 保持 0.1 左右creative 可以到 0.8build 居中。第三定期清理 skills 目录里不再用的技能避免触发冲突。第四配置改动后一定重启会话opencode 不会热加载opencode.json。最后说一个我自己的习惯把opencode.json纳入版本管理去掉 Key 等敏感信息这样换机器时直接拉下来就能用Agent 和技能配置不会丢。跑通这套之后你会发现 opencode 不再是一个「问答工具」而是一支随叫随到、分工明确的小团队。