跳到主要内容

外部编码工具

CountBot 可以把外部编码 CLI 接进系统，作为一个可配置的编码执行层。它的定位不是替代主模型，而是在需要时承接编码、调试、重构、命令执行这类工作，或者直接作为某个 IM 渠道账号的默认目标。

为什么要单独一章​

外部编码工具不是普通“第三方集成”，它同时影响三件事：

  • Web 与 IM 中的编码任务怎么执行
  • 渠道账号默认路由如何工作
  • 当前聊天如何在 ai 与 direct 间切换

所以这块最好单独看，而不是混在渠道配置里一笔带过。

支持什么类型的工具​

适合接入的通常是可通过命令行启动的编码工具，例如：

  • Claude Code
  • Codex CLI
  • OpenCode
  • 其他本地 CLI 编码代理

配置文件​

配置存储在 workspace/external_coding_tools.json：

{
  "version": 1,
  "profiles": [
    {
      "name": "claude",
      "aliases": ["claude-code"],
      "type": "cli",
      "enabled": false,
      "command": "claude",
      "args": ["-p", "{prompt}"],
      "working_dir": "",
      "inherit_env": ["ANTHROPIC_API_KEY"],
      "session_mode": "native",
      "history_message_count": 10,
      "timeout": 900
    },
    {
      "name": "codex",
      "aliases": ["openai-codex"],
      "type": "cli",
      "enabled": false,
      "command": "codex",
      "args": ["exec", "--skip-git-repo-check", "--cd", "{working_dir}", "-"],
      "working_dir": "",
      "stdin_template": "{prompt}",
      "inherit_env": ["OPENAI_API_KEY"],
      "session_mode": "history",
      "history_message_count": 10,
      "timeout": 900
    },
    {
      "name": "opencode",
      "aliases": ["open-code"],
      "type": "cli",
      "enabled": false,
      "command": "opencode",
      "args": ["run", "{prompt}"],
      "working_dir": "",
      "inherit_env": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
      "session_mode": "history",
      "history_message_count": 10,
      "timeout": 900
    }
  ]
}

默认创建 3 个 profile，全部默认禁用。需要手动启用并配置 API Key。

Profile 字段说明​

字段类型说明
namestringProfile 名称，必须唯一
aliasesstring[]别名列表
typestring适配器类型，当前仅支持 cli
enabledbool是否启用
commandstring启动命令
argsstring[]参数列表，支持 {prompt}、{working_dir} 占位符
stdin_templatestring标准输入模板，支持 {prompt} 占位符
working_dirstring工作目录
envobject自定义环境变量
inherit_envstring[]从父进程继承的环境变量名列表
session_modestring会话模式：stateless、history、native
history_message_countint携带的历史消息条数（1-50）
timeoutint超时秒数
success_exit_codesint[]成功退出码列表，默认 [0]

会话模式​

session_mode 决定携带多少历史消息给外部编码工具：

模式行为
stateless只发当前任务，不带历史
history携带最近 history_message_count 条历史消息
native使用工具自身的会话能力（如 Claude Code 的内置会话）

注意事项​

  • claude profile 默认 session_mode: "native"，适合与 Claude Code 交互
  • codex 和 opencode 默认 session_mode: "history"
  • native 模式需要外部工具本身支持会话保持，否则可能行为不一致
  • 默认 history_message_count 为 10，范围 1-50

与渠道默认路由的关系​

每个 IM 渠道账号都可以保存两项高级设置：

  • 默认路由模式 routing_mode
  • 默认外部编码工具 external_coding_profile

routing_mode=ai​

普通消息先进 CountBot 主 Agent，再由主模型决定是否调用外部编码工具。

routing_mode=direct​

普通消息直接转发给当前账号绑定的外部编码工具，适合持续编码场景。

如果渠道账号配置成 direct 却没有绑定 external_coding_profile，后端会直接拒绝这份渠道配置。

与 IM 命令的关系​

IM 聊天里支持临时切换：

  • /route ai
  • /route direct
  • /route default
  • /coder <profile>
  • /coder default

这几个命令只影响当前聊天，不会修改后台保存的默认值。

详细见 IM 命令。

当前可用 API​

方法路径说明
GET/api/settings/external-coding-tools获取外部编码工具配置
PUT/api/settings/external-coding-tools保存外部编码工具配置
POST/api/settings/external-coding-tools/check检查某个 profile 是否可用

推荐接入顺序​

  1. 先新增一个 profile。
  2. 填写命令、参数、工作目录和环境变量。
  3. 先用检查接口验证 profile 本身可运行。
  4. 再把它绑定到某个 IM 渠道账号。
  5. 最后再通过 /route 和 /coder 在真实聊天里验证行为。

排查思路​

页面看起来已启用，但聊天里没有生效​

优先检查：

  • 该 profile 是否真正启用
  • 渠道账号默认 external_coding_profile 是否指向它
  • 当前聊天是否被 /coder default 或 /route default 恢复成了后台默认值

为什么某个工具“默认开启”​

通常不是系统自动乱开，而是以下之一：

  • 该渠道账号高级设置本来就保存了默认 profile
  • 当前聊天之前执行过 /coder <profile>
  • 当前聊天路由是 direct

为什么会话模式和预期不同​

重点检查：

  • profile 配置的是不是 native
  • 当前工具是否真的支持 native
  • 不支持时是否被运行时自动回退为 history

相关文档​