1. 为什么我把 OpenCode 当主力而不是再装一个聊天插件如果你已经用过 Claude Code、Cursor、Copilot 这类 AI 编程工具第一次接触 OpenCode大概率会有两个感受它更“野”但也更强。OpenCode 不是封闭式 AI 助手而是一套运行在终端里的开源 AI Agent 框架你可以自己选模型、自己配 Agent、自己定义命令甚至把它扩成一个多角色开发团队。再装上 oh-my-opencode 之后它就不只是一个 AI 编程工具而更像一个能拆任务、会并行、懂代码库、能自主推进的大脑。这篇文章不讲空泛概念只讲一件事怎么把 OpenCode oh-my-opencode 真正用到日常开发里并且用 TaoToken 统一 Key 和 API 通道让模型调用、Agent 协作、ulw 工作流全部跑通。适合已经用过 AI 编程助手、不满足于单一模型或单一工作流、希望 AI 更深参与项目理解与重构的开发者。下面所有配置都可以直接复制改掉 Key 就能用。2. 前置准备TaoToken 统一 Key 与 API 通道OpenCode 支持 Claude、GPT、Gemini 等大量模型但如果你每个模型都单独申请 Key、单独配环境变量切换成本会很高。我的做法是用 TaoToken 做统一入口一个 Key 走所有模型OpenCode 里只配一次 baseURL 和 apiKey。先拿到 Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就重新建。TaoToken 的 API 地址是 https://taotoken.net/api 不带任何多余路径。OpenCode 兼容 OpenAI 风格的接口所以配置里 baseURL 填这个地址即可。如果你用的是 Anthropic 协议OpenCode 也支持但为了统一管理我建议先用 OpenAI 兼容模式跑通再按需切换。注意不要把 Key 硬编码进提交到 Git 的配置文件。用环境变量或者 OpenCode 的本地 auth 文件后面会讲。3. 可复制配置settings.json 与 config.toml 骨架OpenCode 的配置分两层全局配置和项目配置。全局配置放在~/.config/opencode/下项目配置放在项目根目录的.opencode/里。oh-my-opencode 安装后会往全局配置里注入 Agent 定义所以先装 oh-my-opencode再改配置。安装 OpenCode 和 oh-my-opencode# 安装 OpenCode curl -fsSL https://opencode.ai/install | bash # 安装 oh-my-opencode bunx oh-my-opencode install装完后编辑全局配置文件~/.config/opencode/config.toml把模型通道指向 TaoToken# ~/.config/opencode/config.toml [provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} [model] provider taotoken name claude-sonnet-4-20250514 [agent.build] model taotoken/claude-sonnet-4-20250514 [agent.plan] model taotoken/claude-sonnet-4-20250514然后在 shell 里导出环境变量export TAOTOKEN_API_KEY你的_TaoToken_Key如果你更习惯 JSON 风格OpenCode 也支持settings.json放在~/.config/opencode/settings.json{ provider: { taotoken: { name: TaoToken, baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} } }, model: taotoken/claude-sonnet-4-20250514, agent: { build: { model: taotoken/claude-sonnet-4-20250514 }, plan: { model: taotoken/claude-sonnet-4-20250514 } } }两种格式选一种就行不要同时存在否则 OpenCode 会按优先级覆盖容易排查半天。我实测下来config.toml 对 oh-my-opencode 注入的 Agent 兼容性更好所以推荐 TOML。4. AGENTS.md让 AI 记住项目规则而不是每次重新说很多人装完 OpenCode 就急着提需求结果 AI 一会儿用错 ORM一会儿越层调用一会儿生成不符合团队规范的代码。原因很简单你没告诉它项目规则。AGENTS.md 就是解决这个问题的文件可以理解成 AI 在这个项目里的长期记忆说明书。进入项目目录启动 OpenCodecd your-project opencode在 TUI 里输入/init它会分析项目结构并生成 AGENTS.md。但自动生成的只是骨架真正有价值的是你手动补进去的约束。我的 AGENTS.md 通常包含这几块# 项目约定 ## 技术栈 - 后端Java 17 Spring Boot 3 - ORMjOOQ禁止使用 Hibernate - 前端React 18 TypeScript ## 构建与测试 - 构建./gradlew build - 测试./gradlew test - 单测覆盖率要求新增代码 ≥ 80% ## 代码规范 - 所有 public 方法必须写 Javadoc - Controller 不能直接调 Repository - 异常统一进 GlobalExceptionHandler - 禁止循环内查数据库 ## 禁止事项 - 不要修改 build.gradle 里的依赖版本 - 不要动 src/main/resources/application-prod.yml这份文件一定要提交到 Git。它不是临时文件而是团队与 AI 协作的项目约定。你重复说十次不如沉淀成长期记忆一次。5. ulw 工作流从“问答工具”升级成“执行型 Agent”oh-my-opencode 装完后最值得记住的只有一个词ulw也就是 ultrawork 的缩写。你只要在提示词里带上这个词oh-my-opencode 就会自动进入更强的执行状态主动探索代码库、自己寻找实现参考、并行调用多个子 Agent、不轻易中断来问你、持续验证结果直到完成。适合直接 ulw 的任务ulw 给 /api/orders 接口增加分页功能参考 /api/products 的实现方式 ulw 找出所有 N1 查询问题并修复 ulw 将整个项目的错误处理统一改为 Result 模式 ulw 重构 src/payment/ 为策略模式对外接口不变不适合急着 ulw 的场景需求边界不清、涉及关键架构决策、你想先把方案审一遍。这种时候先切到 Plan Agent让它出方案你确认后再切回 Build 执行。oh-my-opencode 安装后会多出一批角色鲜明的 Agent主 Agent 里 Sisyphus 是默认编排者适合日常任务和 ulwHephaestus 适合深度独立执行的大任务Prometheus 擅长需求梳理和反问澄清Atlas 执行计划型任务。子 Agent 里 oracle 做架构顾问和逻辑审查metis 补计划漏洞momus 做质量把关explore 搜索代码库librarian 查文档multimodal-looker 看图还原 UI。这套设计很像真实开发团队有人提方案有人执行有人检查有人调研有人架构把关。所以它强的不是模型更聪明而是协作方式更像工程化团队。6. 验证请求确认 Agent 正常调用、AGENTS.md 生效、ulw 跑通配置写完不算完必须验证三件事Agent 能正常调用模型、AGENTS.md 被读取、ulw 工作流能跑通。第一步启动 OpenCode 后先做一次最小请求opencode在 TUI 里输入explore 列出这个项目的所有 API 入口点如果 explore 能返回路由和 Handler 列表说明子 Agent 调度正常TaoToken 通道也通了。如果报 401检查TAOTOKEN_API_KEY是否导出成功如果报模型不存在检查 config.toml 里的 model name 是否拼错。第二步验证 AGENTS.md 生效。在 TUI 里问这个项目用的是什么 ORM如果它回答 jOOQ 而不是 Hibernate说明 AGENTS.md 被正确读取。如果回答不对检查 AGENTS.md 是否在项目根目录以及是否已经/init过。第三步验证 ulw 工作流。找一个小任务试ulw 给 src/utils/date.ts 增加一个 formatRelativeTime 函数并补单测观察它是否主动探索代码库、是否并行调用子 Agent、是否自己跑测试验证。如果它中途频繁停下来问你说明 ulw 没触发检查 oh-my-opencode 是否安装成功可以用bunx oh-my-opencode doctor做自检。7. 本篇常见错排查报错一Provider taotoken not foundconfig.toml 里 provider 段名和 model 前缀不一致。provider 段叫[provider.taotoken]model 就必须写taotoken/xxx大小写敏感。报错二401 Unauthorized环境变量没导出或者 Key 复制时带了空格。用echo $TAOTOKEN_API_KEY确认重新导出后重启 OpenCode。报错三/init生成的 AGENTS.md 是空的项目目录没有 Git 仓库或者文件太多被忽略。先git init再在项目根目录执行/init。报错四ulw 不触发Agent 还是单线程oh-my-opencode 没装成功或者版本和 OpenCode 不匹配。重新执行bunx oh-my-opencode install然后bunx oh-my-opencode doctor看输出。报错五/undo和/redo不生效这两个命令依赖 Git 管理变更。项目必须从第一天就放在 Git 仓库里否则无法回滚。报错六上下文越来越重响应变慢大任务做久了直接/compact它会压缩会话保留关键上下文减轻 token 压力。不要硬聊。8. 把 OpenCode 用顺之后我的三条真实经验第一条小任务别过度编排大任务别一句话梭哈。改 1 到 2 个文件直接做中等任务先规划再执行大任务用 ulw 或/start-work。/start-work适合跨模块、需求复杂、希望中断后还能恢复的场景它会保留执行状态。第二条把项目规则写进 AGENTS.md而不是每次重新说。重复说十次不如沉淀成长期记忆一次。第三条让不同 Agent 做不同事。搜索交给 explore架构判断交给 oracle规划交给 Prometheus自动推进交给 Sisyphus ulw。不要让一个 Agent 同时扮演所有角色。如果你已经过了“拿 AI 补几个函数”的阶段想往更高阶的工作流走这套组合值得认真用一段时间。它不是最傻瓜的但一旦用顺确实会越来越离不开。需要统一 Key 和 API 通道的话可以从 https://taotoken.net/api-keys 建一个再按上面的 config.toml 接进 OpenCode剩下的就是让 Agent 干活了。
我把 OpenCode + oh-my-opencode 用透了：一份真正能落地的最佳实践（TaoToken 配置篇）
1. 为什么我把 OpenCode 当主力而不是再装一个聊天插件如果你已经用过 Claude Code、Cursor、Copilot 这类 AI 编程工具第一次接触 OpenCode大概率会有两个感受它更“野”但也更强。OpenCode 不是封闭式 AI 助手而是一套运行在终端里的开源 AI Agent 框架你可以自己选模型、自己配 Agent、自己定义命令甚至把它扩成一个多角色开发团队。再装上 oh-my-opencode 之后它就不只是一个 AI 编程工具而更像一个能拆任务、会并行、懂代码库、能自主推进的大脑。这篇文章不讲空泛概念只讲一件事怎么把 OpenCode oh-my-opencode 真正用到日常开发里并且用 TaoToken 统一 Key 和 API 通道让模型调用、Agent 协作、ulw 工作流全部跑通。适合已经用过 AI 编程助手、不满足于单一模型或单一工作流、希望 AI 更深参与项目理解与重构的开发者。下面所有配置都可以直接复制改掉 Key 就能用。2. 前置准备TaoToken 统一 Key 与 API 通道OpenCode 支持 Claude、GPT、Gemini 等大量模型但如果你每个模型都单独申请 Key、单独配环境变量切换成本会很高。我的做法是用 TaoToken 做统一入口一个 Key 走所有模型OpenCode 里只配一次 baseURL 和 apiKey。先拿到 Key打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就重新建。TaoToken 的 API 地址是 https://taotoken.net/api 不带任何多余路径。OpenCode 兼容 OpenAI 风格的接口所以配置里 baseURL 填这个地址即可。如果你用的是 Anthropic 协议OpenCode 也支持但为了统一管理我建议先用 OpenAI 兼容模式跑通再按需切换。注意不要把 Key 硬编码进提交到 Git 的配置文件。用环境变量或者 OpenCode 的本地 auth 文件后面会讲。3. 可复制配置settings.json 与 config.toml 骨架OpenCode 的配置分两层全局配置和项目配置。全局配置放在~/.config/opencode/下项目配置放在项目根目录的.opencode/里。oh-my-opencode 安装后会往全局配置里注入 Agent 定义所以先装 oh-my-opencode再改配置。安装 OpenCode 和 oh-my-opencode# 安装 OpenCode curl -fsSL https://opencode.ai/install | bash # 安装 oh-my-opencode bunx oh-my-opencode install装完后编辑全局配置文件~/.config/opencode/config.toml把模型通道指向 TaoToken# ~/.config/opencode/config.toml [provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} [model] provider taotoken name claude-sonnet-4-20250514 [agent.build] model taotoken/claude-sonnet-4-20250514 [agent.plan] model taotoken/claude-sonnet-4-20250514然后在 shell 里导出环境变量export TAOTOKEN_API_KEY你的_TaoToken_Key如果你更习惯 JSON 风格OpenCode 也支持settings.json放在~/.config/opencode/settings.json{ provider: { taotoken: { name: TaoToken, baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} } }, model: taotoken/claude-sonnet-4-20250514, agent: { build: { model: taotoken/claude-sonnet-4-20250514 }, plan: { model: taotoken/claude-sonnet-4-20250514 } } }两种格式选一种就行不要同时存在否则 OpenCode 会按优先级覆盖容易排查半天。我实测下来config.toml 对 oh-my-opencode 注入的 Agent 兼容性更好所以推荐 TOML。4. AGENTS.md让 AI 记住项目规则而不是每次重新说很多人装完 OpenCode 就急着提需求结果 AI 一会儿用错 ORM一会儿越层调用一会儿生成不符合团队规范的代码。原因很简单你没告诉它项目规则。AGENTS.md 就是解决这个问题的文件可以理解成 AI 在这个项目里的长期记忆说明书。进入项目目录启动 OpenCodecd your-project opencode在 TUI 里输入/init它会分析项目结构并生成 AGENTS.md。但自动生成的只是骨架真正有价值的是你手动补进去的约束。我的 AGENTS.md 通常包含这几块# 项目约定 ## 技术栈 - 后端Java 17 Spring Boot 3 - ORMjOOQ禁止使用 Hibernate - 前端React 18 TypeScript ## 构建与测试 - 构建./gradlew build - 测试./gradlew test - 单测覆盖率要求新增代码 ≥ 80% ## 代码规范 - 所有 public 方法必须写 Javadoc - Controller 不能直接调 Repository - 异常统一进 GlobalExceptionHandler - 禁止循环内查数据库 ## 禁止事项 - 不要修改 build.gradle 里的依赖版本 - 不要动 src/main/resources/application-prod.yml这份文件一定要提交到 Git。它不是临时文件而是团队与 AI 协作的项目约定。你重复说十次不如沉淀成长期记忆一次。5. ulw 工作流从“问答工具”升级成“执行型 Agent”oh-my-opencode 装完后最值得记住的只有一个词ulw也就是 ultrawork 的缩写。你只要在提示词里带上这个词oh-my-opencode 就会自动进入更强的执行状态主动探索代码库、自己寻找实现参考、并行调用多个子 Agent、不轻易中断来问你、持续验证结果直到完成。适合直接 ulw 的任务ulw 给 /api/orders 接口增加分页功能参考 /api/products 的实现方式 ulw 找出所有 N1 查询问题并修复 ulw 将整个项目的错误处理统一改为 Result 模式 ulw 重构 src/payment/ 为策略模式对外接口不变不适合急着 ulw 的场景需求边界不清、涉及关键架构决策、你想先把方案审一遍。这种时候先切到 Plan Agent让它出方案你确认后再切回 Build 执行。oh-my-opencode 安装后会多出一批角色鲜明的 Agent主 Agent 里 Sisyphus 是默认编排者适合日常任务和 ulwHephaestus 适合深度独立执行的大任务Prometheus 擅长需求梳理和反问澄清Atlas 执行计划型任务。子 Agent 里 oracle 做架构顾问和逻辑审查metis 补计划漏洞momus 做质量把关explore 搜索代码库librarian 查文档multimodal-looker 看图还原 UI。这套设计很像真实开发团队有人提方案有人执行有人检查有人调研有人架构把关。所以它强的不是模型更聪明而是协作方式更像工程化团队。6. 验证请求确认 Agent 正常调用、AGENTS.md 生效、ulw 跑通配置写完不算完必须验证三件事Agent 能正常调用模型、AGENTS.md 被读取、ulw 工作流能跑通。第一步启动 OpenCode 后先做一次最小请求opencode在 TUI 里输入explore 列出这个项目的所有 API 入口点如果 explore 能返回路由和 Handler 列表说明子 Agent 调度正常TaoToken 通道也通了。如果报 401检查TAOTOKEN_API_KEY是否导出成功如果报模型不存在检查 config.toml 里的 model name 是否拼错。第二步验证 AGENTS.md 生效。在 TUI 里问这个项目用的是什么 ORM如果它回答 jOOQ 而不是 Hibernate说明 AGENTS.md 被正确读取。如果回答不对检查 AGENTS.md 是否在项目根目录以及是否已经/init过。第三步验证 ulw 工作流。找一个小任务试ulw 给 src/utils/date.ts 增加一个 formatRelativeTime 函数并补单测观察它是否主动探索代码库、是否并行调用子 Agent、是否自己跑测试验证。如果它中途频繁停下来问你说明 ulw 没触发检查 oh-my-opencode 是否安装成功可以用bunx oh-my-opencode doctor做自检。7. 本篇常见错排查报错一Provider taotoken not foundconfig.toml 里 provider 段名和 model 前缀不一致。provider 段叫[provider.taotoken]model 就必须写taotoken/xxx大小写敏感。报错二401 Unauthorized环境变量没导出或者 Key 复制时带了空格。用echo $TAOTOKEN_API_KEY确认重新导出后重启 OpenCode。报错三/init生成的 AGENTS.md 是空的项目目录没有 Git 仓库或者文件太多被忽略。先git init再在项目根目录执行/init。报错四ulw 不触发Agent 还是单线程oh-my-opencode 没装成功或者版本和 OpenCode 不匹配。重新执行bunx oh-my-opencode install然后bunx oh-my-opencode doctor看输出。报错五/undo和/redo不生效这两个命令依赖 Git 管理变更。项目必须从第一天就放在 Git 仓库里否则无法回滚。报错六上下文越来越重响应变慢大任务做久了直接/compact它会压缩会话保留关键上下文减轻 token 压力。不要硬聊。8. 把 OpenCode 用顺之后我的三条真实经验第一条小任务别过度编排大任务别一句话梭哈。改 1 到 2 个文件直接做中等任务先规划再执行大任务用 ulw 或/start-work。/start-work适合跨模块、需求复杂、希望中断后还能恢复的场景它会保留执行状态。第二条把项目规则写进 AGENTS.md而不是每次重新说。重复说十次不如沉淀成长期记忆一次。第三条让不同 Agent 做不同事。搜索交给 explore架构判断交给 oracle规划交给 Prometheus自动推进交给 Sisyphus ulw。不要让一个 Agent 同时扮演所有角色。如果你已经过了“拿 AI 补几个函数”的阶段想往更高阶的工作流走这套组合值得认真用一段时间。它不是最傻瓜的但一旦用顺确实会越来越离不开。需要统一 Key 和 API 通道的话可以从 https://taotoken.net/api-keys 建一个再按上面的 config.toml 接进 OpenCode剩下的就是让 Agent 干活了。