1. 从聊天窗口到 CLIFree-Claude-Code 消息平台集成要解决什么Free-Claude-Code 是一套把 Claude Code CLI 包装成聊天机器人服务的开源方案它能让你在 Discord 或 Telegram 里直接发消息由后台拉起 Claude Code 子进程完成编码任务再把结果流式回传到聊天窗口。适合谁适合想在手机或团队频道里随手驱动 CLI、又不想每次开终端的人也适合想研究 Bot 中间件架构的工程师。它最核心的两个能力一是消息平台适配层二是树形会话队列。我先把问题摆清楚。传统 Bot 处理消息是先进先出队列用户发一条Bot 处理一条回复一条。单轮问答没问题但编码场景天然是多轮、可分支的。你在 Discord 里回复某条历史消息说“改成迭代版本”在 Telegram 里引用另一条说“用 Java 重写”这两条诉求指向不同的上下文分支。线性队列会把它们串成一条线上下文互相污染最后谁也说不清哪条回复对应哪段代码。Free-Claude-Code 的解法是把每条对话建模成一棵树。根节点是用户的第一条消息回复某条消息就在对应节点下挂子节点。每棵树内部维持 FIFO 串行处理不同树之间并行。再配合fork_session机制从某个历史节点分叉时复用父会话上下文但创建独立的新会话分支之间互不影响。这套设计要跑起来绕不开一个现实问题Claude Code CLI 需要可用的 API 通道和 Key。本文用 TaoToken 统一 Key 配置把config.toml和settings.json的可复制骨架给全再走一遍 Discord/Telegram Bot 的联调验证目标是让你从消息平台到会话队列整条链路跑通。下面按“前置配置 → 可复制配置 → 验证 → 排障 → 分流”的顺序展开。2. TaoToken 前置统一 Key 与 API 通道准备在动 Bot 代码之前先把模型通道打通。Free-Claude-Code 底层调用的是 Claude Code CLICLI 读取的是环境变量和配置文件里的 Base URL 与 Key。TaoToken 提供统一的 API 入口你只需要一个 Key 就能驱动 CLI不用在多个平台之间来回切换。第一步去控制台创建 API Key。打开 https://taotoken.net/console 登录后在 API Keys 页面新建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了只能重建。第二步确认 API 通道地址。TaoToken 的 API 基址是 https://taotoken.net/api 这个地址要写进 CLI 的配置里作为 Anthropic 兼容端点。Claude Code CLI 认的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量或者写进settings.json。第三步选模型 ID。TaoToken 支持多种模型编码场景常用的是 Claude 系列。你可以在模型对话页面先试一下模型是否可用打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一条测试消息确认返回正常。这一步很关键因为后面 Bot 联调如果报 401 或模型不存在先排除通道问题能省很多时间。第四步如果你打算长期跑编码 Agent建议看一下 Coding Plan它更适合高频、长时间的 CLI 调用场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。普通按量调用用 API Key 就够长期跑再考虑套餐。这里要强调一点TaoToken 是合规的 API 聚合通道不是灰色中转。你拿到的 Key 直接用于官方 CLI 的标准接口配置方式和官方文档一致只是 Base URL 指向统一入口。这样做的价值在于一个 Key 管所有模型调用Bot 侧不用维护多套凭证。前置准备清单一个可用的 API Key、确认过的 Base URL、一个测试通过的模型 ID。这三样齐了再往下写配置。3. 可复制配置config.toml 与 settings.json 骨架这一节给可直接复制的配置。Free-Claude-Code 的配置分两层一层是 Claude Code CLI 自己的settings.json管模型通道一层是项目侧的config.toml管消息平台和队列行为。两层的路径要和项目实际结构一致下面按常见布局写。先看 CLI 侧的settings.json。它通常放在~/.claude/settings.json或者项目根目录下由 CLI 读取。核心是 Base URL、Key 和模型 ID 三件套{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(git*), Read, Write, Edit ] } }注意ANTHROPIC_BASE_URL后面不要带斜杠也不要加 UTM 参数API 调用地址就是干净的https://taotoken.net/api。Key 用你在控制台创建的那串。模型 ID 换成你在模型对话页验证通过的那个。再看项目侧的config.toml。Free-Claude-Code 用它来配置消息平台、会话队列和限流参数。放在项目根目录[messaging] # 平台选择: discord / telegram / none platform discord # Discord 配置 discord_bot_token 你的Discord Bot Token discord_allowed_channels [112233445566778899, 998877665544332211] # Telegram 配置platform telegram 时生效 telegram_bot_token 你的Telegram Bot Token telegram_allowed_user_id 123456789 [queue] # 树形队列每棵树内部串行树之间并行 max_concurrent_trees 4 # 单棵树内待处理节点上限防止刷屏 max_pending_per_tree 20 # 节点状态消息的编辑节流窗口秒 status_edit_throttle_secs 1.0 [rate_limit] # 全局消息发送限流窗口内最多 N 条 max_messages_per_window 1 window_secs 1.0 # 触发平台限流后的暂停秒数 flood_wait_pause_secs 30 [cli] # Claude Code CLI 可执行文件路径 claude_bin claude # 工作目录 workspace ./workspace # 是否启用 fork_session 分支 enable_fork_session true [voice] # 语音转写可选 enabled false whisper_model base whisper_device cpu如果你用 Telegram把platform改成telegram填telegram_bot_token和telegram_allowed_user_id。Discord 的discord_allowed_channels填允许 Bot 响应的频道 ID留空表示不限制但生产环境建议限制。关于fork_session它是树形队列的关键开关。开启后当用户回复某个历史节点时CLI 会用--resume session_id --fork-session启动复用父会话上下文但生成新的 session_id。这样分支之间不会互相覆盖。配置里enable_fork_session true就是打开这个行为。环境变量方式也可以适合容器部署export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514 export MESSAGING_PLATFORMdiscord export DISCORD_BOT_TOKEN你的Discord Bot Token配置写完后先单独验证 CLI 能不能通。在终端跑claude -p 用一句话说明快速排序的原理 --output-format stream-json如果返回流式 JSON 且内容正常说明 Key 和 Base URL 没问题。这一步过了再启动 Bot否则 Bot 报错你会分不清是通道问题还是平台问题。4. 验证请求Discord/Telegram Bot 联调与成功结果配置就绪后开始联调。先启动服务再在聊天平台发消息观察状态消息的流转。启动命令项目推荐用 uvuv run python server.py或者直接用 Pythonpython server.py启动日志里应该能看到平台连接成功、队列管理器初始化、SessionStore 加载首次为空。如果看到Messaging platform: discord和Tree queue manager ready说明服务起来了。Discord 侧验证动作。在允许的频道里 Bot 发一条消息Bot 写一个 Python 函数计算斐波那契数列预期现象Bot 先回一条状态消息内容类似“Launching new Claude CLI instance...”然后状态消息被流式编辑逐步显示“Processing...”最后变成“Done”并附上代码块。这条状态消息本身也被注册为树节点你可以直接回复它继续对话。接着验证分支。回复 Bot 刚才那条结果消息发改成迭代版本避免栈溢出预期Bot 识别这是回复消息找到父节点在树里挂子节点CLI 用--resume复用上下文返回迭代版代码。再回复最初那条用户消息发再用 Java 实现一遍预期Bot 从根节点分叉CLI 用--resume 父session --fork-session创建新分支返回 Java 版本。此时树结构是根节点下两个分支互不干扰。Telegram 侧验证动作类似。给 Bot 发消息或者引用某条消息回复。Telegram 的引用回复会带上reply_to_message_id适配器把它转成IncomingMessage.reply_to_message_id后续逻辑和 Discord 一致。语音消息如果开启了voice.enabled发一条语音Bot 会先回“Transcribing...”转写完成后进入正常处理流程。验证成功的标志有三个状态消息能流式更新、回复历史消息能正确分叉、/stop能中断当前任务。/stop的验证方式是发一条耗时任务然后立刻发/stop状态消息应变成“Stopped.”子进程被终止。如果你想确认会话 ID 的映射是否正确可以在日志里找register_real_session_id和fork from parent session这两条记录。前者说明临时 ID 到真实 session_id 的映射建立了后者说明分叉走了fork_session路径。联调阶段建议把日志级别调到 debug能看到队列的入队、出队、节点状态变化。生产环境再调回 info减少日志量。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth联调时最容易撞的几类报错这里逐个对照。401 Unauthorized。现象是 CLI 启动后立刻返回鉴权失败Bot 状态消息变成错误。原因通常是 Key 不对或 Base URL 写错。检查settings.json里的ANTHROPIC_API_KEY是否是完整的 TaoToken KeyANTHROPIC_BASE_URL是否是https://taotoken.net/api不带尾斜杠、不带多余路径。如果环境变量和配置文件同时存在环境变量优先级更高确认没有旧的环境变量覆盖。改完重启服务。local proxy failed / connection refused。现象是 CLI 连不上 API 端点。先确认网络能访问https://taotoken.net/api用 curl 测一下curl -s -o /dev/null -w %{http_code} https://taotoken.net/api如果返回 401 或 404说明端点可达问题在鉴权或路径如果超时说明网络层有问题。注意不要配置任何非官方的网络转发工具直接用系统网络访问即可。另外检查settings.json里有没有残留的旧 Base URL 指向别的地址。reading choices / 解析响应失败。现象是 CLI 收到响应但解析报错日志里出现reading choices之类的字段访问错误。这通常是模型返回格式和 CLI 预期不一致或者模型 ID 写错导致返回了错误结构。确认ANTHROPIC_MODEL是 TaoToken 支持的模型 ID去模型对话页核对。另外检查有没有在配置里混入 OpenAI 格式的参数Claude Code CLI 用的是 Anthropic 格式两者不通用。OAuth 相关报错。现象是 CLI 提示需要登录或 OAuth token 失效。Claude Code CLI 支持 OAuth 登录和 API Key 两种模式。用 TaoToken 统一 Key 时应该走 API Key 模式不要触发 OAuth 流程。检查settings.json里是否残留了 OAuth 相关的凭证字段如果有清掉只保留env里的 Base URL 和 Key。如果 CLI 仍然尝试 OAuth确认启动命令没有带--login之类的参数。Bot 收不到消息。Discord 侧检查三件事Bot 是否已加入目标服务器、Developer Portal 里 MESSAGE CONTENT INTENT 是否开启、频道 ID 是否在discord_allowed_channels里。Telegram 侧检查 Bot Token 是否正确、telegram_allowed_user_id是否包含你的用户 ID。回复消息没有分叉而是新建了树。检查reply_to_message_id是否被正确传递。Discord 里如果消息的reference为空比如原消息被删除适配器拿不到父节点 ID就会新建树。Telegram 论坛话题里还要确认message_thread_id有没有传。另外确认状态消息是否注册到了树里register_node没调用的话回复状态消息也找不到父节点。/stop 后任务还在跑。检查_process_node里的异常处理有没有吞掉asyncio.CancelledError。取消信号是通过抛CancelledError实现的如果代码里写了except Exception把取消也捕获了且没重新抛出取消就会失效。确保取消异常单独处理或重新抛出。服务重启后会话丢失。这是预期行为的一部分。SessionStore 持久化的是消息树结构和 session_id 映射但 CLI 子进程在重启时已被终止PENDING 和 IN_PROGRESS 节点会被标记为 ERROR提示“Lost during server restart”。历史树结构可以恢复用于展示但正在跑的任务无法续跑。要恢复上下文需要重新发消息CLI 会用--resume加载云端会话。6. 语义一致 CTA把链路跑通之后整条链路跑通的顺序是TaoToken 拿 Key → 写settings.json和config.toml→ 单独验证 CLI → 启动 Bot → 平台发消息验证 → 回复历史消息验证分叉 →/stop验证中断。每一步都有明确的成功标志卡在哪一步就查对应章节。如果你在排障阶段反复撞 401 或连接问题先去 API Keys 页面确认 Key 状态再对照接入文档检查配置字段 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有各语言和 CLI 的接入示例配置字段的命名以文档为准。如果你只是想先确认模型通道可用用模型对话页面发一条测试消息最快 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。通道确认后再回来配 Bot能少走弯路。如果你打算把 Free-Claude-Code 长期挂在服务器上跑编码 AgentCoding Plan 更适合高频调用场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。按量调用和套餐的差别主要在成本和配额管理功能上都是同一套 API 通道。最后给一个实用技巧联调阶段把max_concurrent_trees设小一点比如 2方便观察队列行为status_edit_throttle_secs设成 1.0 以上避免触发平台限流。等链路稳定了再按实际负载调整。树形队列的价值在多人多分支场景才明显单用户单线程用起来和线性队列差别不大但一旦有人开始回复历史消息分支隔离的优势就出来了。