魔改 Opencode 实战：用 TypeScript + Bun 搭建 Your-Code Agent 并接入 TaoToken

1. 为什么要魔改 Opencode 做 Your-Code AgentOpencode 是一个 AI 驱动的开发工具自带 CLI、Web 应用和桌面端同时开放了 Agent 系统、Skill 定义和插件机制。简单说它不是一个只能聊天的壳子而是一套可以拆开重组的开发助手框架。你可以把它理解成“编辑器里的智能体运行时”模型负责思考Opencode 负责把思考变成文件读写、命令执行、代码检索这些真实动作。但默认的 Opencode 是通用型的它不知道你的项目叫什么、用什么技术栈、部署流程长什么样。Your-Code Agent 要解决的就是这个问题——把通用 Agent 改造成只服务你当前项目的专属助手。它适合三类人一是想给团队做内部编码助手的开发者二是想研究 Agent 工具调用链路的工程师三是已经用 Opencode 但觉得默认行为不够贴合自己项目的人。我这次用 TypeScript Bun 从零搭了一个最小闭环自定义 Agent 配置、接入 TaoToken 统一 Key 通道、写一个可复制的入口脚本最后在本地跑通一次真实请求。整个过程不需要改 Opencode 源码全部通过配置文件和插件完成。下面按步骤拆开讲每一步都能直接复制。2. TaoToken 前置统一 Key 与 API 通道TaoToken 在这里的角色是“模型调用的统一入口”。你的 Your-Code Agent 不管底层换哪个模型都只需要认一个 baseURL 和一个 API Key。这样做的好处是Agent 配置里不用散落多个厂商的密钥切换模型时只改一个 model 字段不用动请求层代码。先拿到 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制保存。这个 Key 后面会写进环境变量不要硬编码到代码里。TaoToken 的 API 地址是 https://taotoken.net/api 它兼容 OpenAI 风格的请求格式。也就是说任何支持自定义 baseURL 的 SDK 或框架都能直接指向它。Opencode 的 provider 配置里正好有options.baseURL这个字段所以接入成本很低。注意API Key 只显示一次创建后立刻保存到本地.env文件并确保.env在.gitignore里。如果你还没决定用哪个模型可以先到 https://taotoken.net/models 看看当前可用的模型列表记下你要用的模型 ID比如claude-sonnet-4-20250514这类格式。后面配置 Agent 时会用到。3. 可复制配置config.toml 与 settings.json 骨架Opencode 的配置分两层项目级配置放在.opencode/目录下用户级配置放在~/.config/opencode/。我建议把 Your-Code Agent 的定义放在项目级这样每个项目可以有独立的 Agent 行为。先建目录结构mkdir -p .opencode/agents mkdir -p .opencode/skills/your-code-db touch .opencode/config.toml touch .opencode/settings.json3.1 config.tomlAgent 与 Provider 骨架.opencode/config.toml负责声明 provider 和默认模型。这里把 baseURL 指向 TaoToken[provider.taotoken] name TaoToken npm ai-sdk/openai-compatible [provider.taotoken.options] baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} [provider.taotoken.models] claude-sonnet-4-20250514 { name Claude Sonnet 4 } gpt-4.1 { name GPT-4.1 } [agent.your-code] description Your-Code 专属开发助手 mode primary model taotoken/claude-sonnet-4-20250514 temperature 0.3{env:TAOTOKEN_API_KEY}是 Opencode 支持的环境变量插值语法运行时从环境变量读取避免密钥进仓库。3.2 settings.json工具权限与行为.opencode/settings.json控制 Agent 能用哪些工具、哪些操作需要确认{ $schema: https://opencode.ai/config.json, agent: { your-code: { tools: { write: true, edit: true, bash: true, webfetch: false }, permission: { edit: ask, bash: { git *: allow, bun *: allow, rm *: ask } } } } }这里的关键点是permission.bashgit和bun命令直接放行rm必须人工确认。这样 Agent 在跑构建、装依赖时不会频繁打断你但删除操作仍然受控。3.3 Agent 入口代码片段除了配置文件Your-Code Agent 还需要一个入口脚本用来在启动时注入项目上下文。在项目根目录建your-code-agent.tsimport { createAgent } from opencode-ai/sdk; const agent createAgent({ name: your-code, model: taotoken/claude-sonnet-4-20250514, systemPrompt: 你是 Your-Code 项目的专属开发助手。 项目技术栈TypeScript Bun。 代码规范使用 2 空格缩进函数优先使用箭头函数。 修改代码前先说明意图涉及删除操作必须请求确认。, tools: [read, write, edit, bash], }); export default agent;这个脚本的作用是把项目特有的规则写进 system prompt。Opencode 启动时会加载它Agent 在每次对话中都带着这些约束。4. 验证请求本地启动与成功结果配置写完后先装依赖再启动。确保 Bun 版本在 1.3.10 以上bun --version如果低于这个版本先升级bun upgrade然后安装项目依赖bun install设置环境变量并启动 CLIexport TAOTOKEN_API_KEY你的Key bun run dev启动后你会看到 Opencode 的交互界面。输入一条测试指令比如帮我读取 package.json告诉我项目名称和依赖数量如果配置正确Agent 会调用 read 工具读取文件然后返回结果。成功输出类似项目名称your-code-agent 依赖数量12再测一次写操作验证权限控制在项目根目录创建一个 hello.ts内容是一个打印 Your-Code Agent ready 的函数Agent 会先请求确认你输入y后它才会写入文件。写入完成后用cat hello.ts检查内容是否正确。最后验证 TaoToken 通道是否真的生效。在 Agent 对话里问你当前使用的模型是什么如果返回的模型 ID 是claude-sonnet-4-20250514说明请求确实走了 TaoToken 的 baseURL。你也可以到 https://taotoken.net/console 查看调用记录确认请求已经到达。5. 本篇常见错排查5.1 Agent 不生效启动后还是默认助手最常见的原因是配置文件位置不对。Opencode 只认.opencode/目录下的config.toml和settings.json。如果你把文件放在了项目根目录它不会加载。检查ls -la .opencode/确认config.toml和settings.json都在里面。另外config.toml里的[agent.your-code]段名必须和 settings.json 里的 key 一致否则权限配置对不上。5.2 请求报 401 或 invalid api key先确认环境变量有没有导出echo $TAOTOKEN_API_KEY如果为空说明export没生效。可以在.env文件里写TAOTOKEN_API_KEY你的Key然后用bun --env-file.env run dev启动。注意 Key 不要有多余空格复制时容易带上换行。5.3 baseURL 写错导致连接超时TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/v1或带其他路径。Opencode 的 openai-compatible provider 会自动拼接/chat/completions。如果你手动加了/v1最终路径会变成/api/v1/chat/completions导致 404。5.4 bash 工具被拒绝执行检查settings.json里的 permission 规则。bun *: allow只匹配以bun开头的命令。如果你执行的是bunx或./node_modules/.bin/xxx不会被匹配。需要显式加规则bash: { bun *: allow, bunx *: allow, ./node_modules/.bin/*: allow }5.5 模型返回内容为空这种情况通常是模型 ID 写错了。TaoToken 的模型 ID 必须和 https://taotoken.net/models 上列出的完全一致。比如claude-sonnet-4-20250514不能简写成claude-sonnet-4。改完config.toml后重启 Opencode 生效。6. 继续深入Skill 与 Coding PlanYour-Code Agent 跑通最小闭环后下一步可以加 Skill。Skill 是一段 Markdown 定义的能力说明放在.opencode/skills/下Agent 会在需要时自动加载。比如给数据库操作写一个 Skill--- name: your-code-db description: Your-Code 项目数据库操作规范 version: 1.0 --- # 数据库操作规范 ## 查询 使用 db.query 而不是 db.execute避免 SQL 注入。 ## 事务 多表写入必须包在 db.transaction 里。 ## 迁移 新增字段先写 migration 文件不要直接改表结构。Agent 在遇到数据库相关任务时会读取这个 Skill按里面的规则执行。如果你打算长期用 Your-Code Agent 做编码和 Agent 任务可以看看 Coding Planhttps://taotoken.net/coding-plan 。它适合需要稳定调用、批量任务和长期运行的场景。日常调试模型行为时用模型对话页面 https://taotoken.net/models 快速验证输出即可。接入文档在 https://taotoken.net/doc 里面有完整的 provider 配置示例和错误码说明。整套流程跑下来核心就三件事配置文件声明 Agent 行为、环境变量注入 Key、入口脚本注入项目上下文。剩下的就是按你的项目需求不断调整 system prompt 和 Skill 内容。