ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

【Agent】【OpenCode】用户对话提示词(system-reminder)配置避坑:TaoToken 统一 Key 接入 settings.json 骨架

【Agent】【OpenCode】用户对话提示词(system-reminder)配置避坑:TaoToken 统一 Key 接入 settings.json 骨架 1. OpenCode 里 system-reminder 和模型通道为什么总对不上如果你正在用 OpenCode 做本地 Agent 开发大概率遇到过这种场景明明在settings.json里配好了模型通道对话也能返回内容但 Agent 的行为就是不对劲——该读文件的时候不读该遵守的代码风格约束当耳旁风甚至把system-reminder里的系统提示当成用户指令直接复述出来。问题往往不在模型本身而是 system-reminder 提示词注入链路和 API 通道配置没有对齐。OpenCode 的 Agent 架构里system-reminder是客户端在把消息发给模型之前自动夹带进去的私有指令层。它和用户输入、工具返回结果一起构成一个三明治结构用户原始输入在最外层工具执行结果在中间system-reminder 作为系统级元数据贴在消息尾部。模型能看到它但用户看不到也不应该把它当成对话内容引用。这个机制本身设计得很干净但一旦你换了模型通道——比如从默认通道切到 TaoToken 统一 Key 接入——注入格式、字段命名、请求头都会影响 system-reminder 是否被正确识别。我试过在同一个 OpenCode 实例里切换两套 Key 配置一套能正常触发文件感知提醒另一套完全静默。排查下来发现是settings.json里 provider 段的baseURL和apiKey字段没有和 OpenCode 的 reminder 注入模块对齐导致客户端以为自己在跟一个不支持 system 角色的端点通信于是主动把 reminder 降级成了普通用户消息。这篇就围绕这个坑把 settings.json 骨架、system-reminder 字段说明、以及一次可复现的对话验证动作讲清楚。2. TaoToken 统一 Key 在 OpenCode 里的定位TaoToken 在这里扮演的角色是模型通道的统一入口。你不需要在 OpenCode 里为每个模型单独维护一套 Key 和端点而是通过一个统一 Key 走同一个 API 地址由 TaoToken 侧完成模型路由。对 OpenCode 来说它只需要知道三件事请求发到哪、用什么身份、目标模型是谁。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时直接写裸地址。OpenCode 的settings.json里 provider 段需要填的就是这个 base URL加上你在控制台生成的 Key。这里有个容易踩的点OpenCode 默认会往请求里塞system角色的消息而部分自定义端点如果没声明支持 system role客户端会做兼容降级。TaoToken 的 API 是兼容标准 chat completions 格式的system 角色可以正常传递所以 system-reminder 不会被吞掉。但前提是你的settings.json里 provider 类型要写对不能写成某些只支持user/assistant的简化模式。Key 的获取在控制台完成地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 生成后到 API Keys 页面复制页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。这两个 deep link 都带了 utm_source 和 utm_content方便你直接跳转。3. settings.json 配置骨架与 system-reminder 字段说明下面这份骨架是我实测能跑通 system-reminder 注入的最小配置。你把它放到 OpenCode 的配置目录下替换掉YOUR_TAOTOKEN_KEY即可。{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY, models: { default: { id: claude-sonnet-4-20250514, maxTokens: 8192, temperature: 0.2 } } } }, agent: { systemReminder: { enabled: true, injectRole: system, wrapTag: system-reminder, maxPerTurn: 3, rules: [ { match: file:*.test.*, template: 当前文件是测试文件请使用项目实际测试框架语法不要写业务逻辑。 }, { match: file:*.env*, template: 这是敏感配置文件禁止在回复中展示任何密钥内容。 }, { match: editor:active, template: 当前活动编辑器文件是 {{activeFile}}请优先检查它。 } ] } } }关键字段逐个说。provider.type必须是openai-compatible这样 OpenCode 才会用标准 chat completions 格式发请求system 角色不会被降级。baseURL写https://taotoken.net/api不要带尾部斜杠也不要加 UTM 参数否则部分 HTTP 客户端会把 query string 拼进路径导致 404。agent.systemReminder.injectRole控制 reminder 以什么角色注入。设成system时reminder 会作为独立 system 消息附加在对话历史末尾模型能明确区分这是系统指令而非用户输入。如果设成user模型容易把 reminder 当成用户说的话出现复述标签内容的情况。wrapTag决定包裹标签名默认就是system-reminder。OpenCode 客户端在注入时会生成system-reminder.../system-reminder结构模型侧通过这个标签识别系统提示边界。maxPerTurn限制单轮对话最多注入几条 reminder防止规则命中过多把上下文撑爆。rules数组是 reminder 的生成规则每条包含match和template。match支持file:前缀匹配文件名、editor:匹配编辑器状态。template里可以用{{activeFile}}这类占位符客户端在注入前会做字符串替换。这套规则是纯 If-This-Then-That 逻辑不需要模型推理客户端自己就能完成。4. 一次对话触发验证确认提示词注入与通道都生效配置写完后别急着跑复杂任务先用一次最小对话验证两件事API 通道通不通system-reminder 有没有被注入。第一步在 OpenCode 里打开一个测试文件比如demo.test.js让编辑器处于活动状态。第二步在对话框输入一句简单指令帮我看看这个文件有没有问题第三步观察返回结果。如果配置正确模型应该会提到“这是测试文件”相关的约束或者直接针对demo.test.js的内容做分析而不是泛泛而谈。这说明file:*.test.*规则命中了reminder 被注入并且模型读到了。如果你想更直观地确认注入内容可以在 OpenCode 里开启调试日志。在settings.json顶层加一段{ debug: { logReminder: true, logPath: ./opencode-reminder.log } }重启 OpenCode 后再发一次对话打开opencode-reminder.log你应该能看到类似这样的记录[reminder] inject rolesystem tagsystem-reminder [reminder] matched rulefile:*.test.* template当前文件是测试文件... [reminder] payload{model:claude-sonnet-4-20250514,messages:[...]}如果日志里inject role显示的是user而不是system说明injectRole字段没生效回去检查拼写。如果日志里完全没有 reminder 记录说明enabled是 false 或者规则没命中。如果日志有 reminder 但请求返回 401那就是 Key 或 baseURL 的问题去 API Keys 页面重新确认 Key 状态。通道验证还有一个更直接的办法用 curl 手动打一次 TaoToken 的 API确认 Key 本身可用。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [ {role: system, content: system-reminder当前文件是测试文件/system-reminder}, {role: user, content: 收到请回复 ok} ] }返回里如果choices[0].message.content包含ok说明通道和 system 角色都正常。这一步能排除掉 OpenCode 客户端本身的干扰把问题范围缩小到配置层。5. 本篇常见错排查报错一401 Unauthorized但 Key 明明是对的。先检查baseURL是不是写成了https://taotoken.net/api/带尾斜杠部分 HTTP 库会把/v1/chat/completions拼成//v1/...导致鉴权失败。另外确认 Key 没有多余空格从 API Keys 页面复制时容易带上换行。报错二模型回复里直接出现了system-reminder标签内容。这是injectRole设成了user的典型症状。模型把 reminder 当成了用户消息于是“礼貌地”复述了一遍。改成system后重新对话即可。如果改了还不行检查 OpenCode 版本是否支持 system 角色注入老版本可能需要升级。报错三reminder 规则不命中。match字段是大小写敏感的file:*.test.*不会匹配Demo.TEST.js。另外editor:active规则依赖编辑器状态上报如果 OpenCode 没拿到活动文件信息这条规则会静默跳过。可以在调试日志里看matched rule字段确认。报错四对话能返回但 Agent 不执行工具调用。这通常不是 reminder 的问题而是模型通道返回的 tool_calls 格式和 OpenCode 预期不一致。确认provider.type是openai-compatible并且模型 ID 在 TaoToken 侧是支持 function calling 的。如果模型本身不支持工具调用Agent 就只能纯聊天。报错五maxPerTurn设太大导致上下文超限。规则多的时候单轮可能命中十几条 reminder把 token 预算吃光。建议maxPerTurn控制在 3 到 5 之间优先级高的规则放前面客户端会按顺序截断。6. 接入与排障的下一步如果你在排障过程中需要重新生成 Key 或查看用量直接走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 里面有完整的请求格式和字段说明遇到 4xx 报错可以先对照文档确认参数。想先验证模型通道是否正常不折腾 OpenCode 配置的话可以用模型对话页面直接发一条带 system 角色的消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。如果那边能正常返回说明 Key 和通道没问题问题就锁定在 OpenCode 的 settings.json 上。长期跑编码 Agent 的话Coding Plan 页面有更完整的通道配置建议https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。Claude Code 相关的 Anthropic 兼容配置在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 如果你用的是 Claude 系模型跑 OpenCode那边的字段命名和这边基本一致可以直接参考。最后留一个实用习惯每次改完settings.json先跑一次第 4 节的最小对话验证确认 reminder 日志里有inject rolesystem再进入正式任务。这个动作花不了三十秒但能省掉后面半小时的“为什么 Agent 不听话”排查。
返回列表