Learn-Claude-Code 笔记 | Concurrency | s08 Background Tasks 的 Base URL 改到 TaoToken 实践-北京尧图网络

1. 从 s08 Background Tasks 说起为什么同步工具调用会卡住整个 Agent如果你正在跟着 learn-claude-code 这个开源项目学 Claude Code 的底层实现学到 Concurrency 这一部分时大概率会在 s08 Background Tasks 这里停一下。原因很简单前面 s01 到 s07整个 agent loop 一直是同步的——模型发一个工具调用程序执行等结果回来再塞进 messages继续下一轮。这个节奏在 read_file、write_file、task_create 这些短操作上完全没问题但一旦遇到pytest、npm install、docker build这种要跑几分钟的命令主循环就被死死卡住了。s08 要解决的核心问题就是当某些工具调用很慢时Agent 如何把它们放到后台执行同时让主循环继续推进文档里给的方案很克制——不推翻原来的 loop而是在 loop 外围加一个后台执行层主线程继续跑 agent loop后台线程去执行慢命令完成后把结果放进通知队列在下一次 LLM 调用之前统一注入回上下文。这套机制本身设计得很漂亮但真正落地到日常开发时还有一个绕不开的前置问题你的 Base URL 指向哪里如果你用的是官方 Anthropic 端点在国内网络环境下调用会非常不稳定后台任务刚跑起来主循环那边 LLM 调用就超时了整个并发验证根本做不下去。所以这篇笔记的重点除了梳理 s08 的后台任务调度机制还会把 Base URL 改到 TaoToken 的完整配置过程写清楚让你能真正把 s08 的并发能力跑起来验证。TaoToken 在这里扮演的角色很明确它提供统一的 API 通道你只需要一个 Key、一个 Base URL就能稳定调用 Claude 系列模型。对于 s08 这种需要频繁发起 LLM 调用每一轮 loop 都要调一次的场景来说通道稳定性直接决定了后台任务机制能不能被验证成功。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 下面会给出可直接复制的配置片段。2. TaoToken 前置准备拿到统一 Key 和 Base URL在改配置之前先把 TaoToken 这边的准备工作做完。这一步不复杂但有几个细节容易踩坑我按顺序说清楚。首先访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录之后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。在控制台里你能看到账户余额、调用统计以及最关键的 API Keys 管理入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。在 API Keys 页面创建一个新的 Key。创建时注意两点一是 Key 只在创建时完整显示一次复制后立刻保存到安全的地方二是如果你打算在多个项目里共用建议按项目命名方便后面排查问题时定位是哪个 Key 出的错。创建完成后你会拿到一串以sk-开头的字符串这就是后面配置里要填的ANTHROPIC_AUTH_TOKEN。接下来确认 Base URL。TaoToken 的 API 端点是https://taotoken.net/api注意这里不要加 UTM 参数API 调用只需要干净的端点地址。这个地址会作为ANTHROPIC_BASE_URL填进环境变量或配置文件。关于模型 IDTaoToken 支持 Claude 系列模型你在配置里填的ANTHROPIC_MODEL需要和 TaoToken 侧支持的模型名一致。常见的比如claude-sonnet-4-20250514、claude-3-5-sonnet-20241022等。如果你不确定当前账户支持哪些模型可以在模型对话页面先手动测一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。在对话页面选一个模型发一条消息能正常返回就说明这个模型 ID 可用然后再把它填进 s08 的配置里。这里有个容易忽略的点s08 的 agent loop 每一轮都会调用一次 LLM如果你的后台任务跑了 5 秒主循环在这 5 秒里可能已经发起了 2 到 3 次 LLM 调用。所以 Key 的额度和通道稳定性都要提前确认好避免跑到一半因为额度不足或通道抖动导致 loop 中断。控制台里的调用统计可以帮你观察这一点。另外如果你打算长期跑 coding 类任务或者 Agent 实验可以看一下 Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对的就是这种高频、长时运行的编码场景比按量付费更适合做 s08 这种并发验证。3. 可复制配置把 s08 的 Base URL 改到 TaoTokens08 的代码本身用的是 Anthropic SDK所以配置方式和 Claude Code 是一致的通过环境变量或者.env文件指定 Base URL、Key 和 Model。下面给出三种常见形态你按自己项目的实际情况选一种。方式一.env文件推荐learn-claude-code 项目默认用这个在项目根目录创建或编辑.env文件写入ANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 ANTHROPIC_MODELclaude-sonnet-4-20250514注意ANTHROPIC_AUTH_TOKEN后面直接跟 Key不要加引号也不要有空格。ANTHROPIC_MODEL填你在模型对话页面验证过可用的那个模型 ID。方式二Claude Code 的 settings.json如果你是在 Claude Code 里跑 s08 的代码配置文件通常在~/.claude/settings.json。写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这个文件路径和字段名要和 Claude Code 实际读取的一致改完重启 Claude Code 生效。方式三Codex 的 auth.json如果你同时用 Codex 做对照实验Codex 的认证文件一般在~/.codex/auth.json写入{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }这里要提醒一句Codex 和 Claude Code 的字段名不一样Claude Code 用ANTHROPIC_*Codex 用OPENAI_*不要混用。如果你在同一个终端里同时跑两个工具建议用不同的 shell 会话避免环境变量互相覆盖。方式四Cline MCP 配置如果你用 Cline 的 MCP 模式接入配置里需要同时写全三件套Base URL、Key、Model ID。在 Cline 的 MCP 设置里填入{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } } } }三件套缺一不可只填 Base URL 不填 Key 会报 401只填 Key 不填 Model ID 会报模型不存在只填 Model ID 不填 Base URL 会走默认端点然后超时。配置改完之后先别急着跑 s08 的完整流程用一条最简单的请求验证通道是否通。在终端里执行curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: reply with ok}] }如果返回里能看到content字段和正常的文本说明 Base URL、Key、Model 三件套都对了。如果返回 401检查 Key 是否复制完整如果返回模型不存在回到模型对话页面确认模型 ID。4. 验证请求跑通 s08 的后台任务并发执行配置通了之后就可以真正验证 s08 的后台任务机制了。这一节我会用文档里给出的第一个 prompt 来演示因为它最能体现 s08 和前面同步模式的区别。第一步确认 s08 代码里的 BackgroundManager 已就位打开agents/s08_background_tasks.py确认这几个关键组件存在BackgroundManager类、run()方法、_execute()方法、drain_notifications()方法以及background_run和check_background两个工具注册。如果是从 s07 升级过来的重点检查agent_loop()开头是否加了这段notifs BG.drain_notifications() if notifs and messages: notif_text \n.join( f[bg:{n[task_id]}] {n[status]}: {n[result]} for n in notifs ) messages.append({role: user, content: fbackground-results\n{notif_text}\n/background-results}) messages.append({role: assistant, content: Noted background results.})这段就是 s08 的精髓在每次新的 LLM 调用之前把通知队列排空并注入上下文。第二步启动 s08输入验证 prompt运行python agents/s08_background_tasks.py在交互界面里输入Run sleep 5 echo done in the background, then create a file while it runs第三步观察 loop 的执行节奏按照文档里的调试分析你应该能看到这样的执行序列第一轮 loop模型返回两个 block一个 TextBlock 说明要去后台跑 sleep 命令一个 ToolUseBlock 调用background_run参数是sleep 5 echo done。BackgroundManager.run()生成 task_id比如17308874在self.tasks里登记statusrunning启动 daemon 线程然后立即返回Background task 17308874 started: sleep 5 echo done。注意这里返回的不是done而是 task_id。第二轮 loop模型拿到任务已启动的确认后没有等待直接调用write_file创建文件。这一步是 s08 和同步模式的分水岭如果是 s01 到 s07 的同步模式主循环会被sleep 5卡住整整 5 秒根本进不到写文件这一步。但现在它做到了因为等待被剥离到了后台线程。第三轮 loop在调用 LLM 之前drain_notifications()被触发把后台线程已经完成的done结果包装成background-results注入 messages。模型看到这个结果后调用read_file读取刚才创建的文件验证内容。第四轮 loop模型调用check_background(task_id17308874)查询单个任务的详细状态返回[completed] sleep 5 echo done done。第五轮 loop模型调用check_background()不传 task_id列出所有后台任务返回17308874: [completed] sleep 5 echo done。第六轮 loop模型输出最终总结循环结束。第四步验证并发能力如果你想更直观地看到并发用文档里的第二个 promptStart 3 background tasks: sleep 2, sleep 4, sleep 6. Check their status.这个 prompt 会连续启动三个后台任务它们在不同的 daemon 线程里并行执行。你可以在终端里观察三个任务几乎同时启动但完成时间分别是 2 秒、4 秒、6 秒。主循环在这期间不会被任何一个任务阻塞可以继续处理其他逻辑。等三个任务都完成后通知队列里会积累三条结果在下一次 LLM 调用前统一注入。第五步确认结果注入的时机这一步是验证 s08 设计是否正确的关键。你可以在drain_notifications()里加一行打印或者在agent_loop()注入background-results的地方加日志。正常情况下你应该看到后台结果不是一完成就立即注入而是在下一次 LLM 调用边界才统一注入。这对应文档里流程图第六张和第七张图强调的结果先在队列里积累直到下一次 LLM call 前才统一 drain。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易遇到的几类报错我按实际踩过的顺序列出来每个都给出定位方法和修复步骤。报错一401 Unauthorized这是最常见的。终端里会看到类似anthropic.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}定位方法先确认ANTHROPIC_AUTH_TOKEN的值是否完整。TaoToken 的 Key 以sk-开头复制时容易漏掉末尾几位。其次确认.env文件是否被正确加载——learn-claude-code 项目用python-dotenv加载如果你在代码里手动改了环境变量但没重启进程旧值还在。修复步骤重新从 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 复制一次 Key粘贴到.env里确保没有多余空格和换行。然后重启 s08 进程。报错二local proxy failed / connection refused这个报错通常长这样httpx.ConnectError: [Errno 111] Connection refused或者anthropic.APIConnectionError: Connection error.定位方法先确认ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api而不是https://taotoken.net/api/v1或其他路径。TaoToken 的端点就是/apiSDK 会自动拼接/v1/messages。如果你手动加了/v1就会变成/api/v1/v1/messages导致 404 或连接失败。修复步骤把 Base URL 改回https://taotoken.net/api不要加任何后缀。然后用第 3 节里的 curl 命令单独测一次确认通道本身是通的。报错三reading choices / 响应解析失败这个报错在流式响应场景下比较常见KeyError: choices或者json.decoder.JSONDecodeError: Expecting value: line 1 column 1定位方法这类报错通常说明返回的不是预期的 JSON 结构。可能原因有两个一是 Base URL 指向了错误的端点返回了 HTML 错误页二是 Model ID 填错了TaoToken 侧返回了错误信息而不是正常的 messages 结构。修复步骤先用 curl 命令看原始返回内容。如果返回的是 HTML说明端点错了如果返回的是 JSON 但结构不对检查 Model ID 是否和 TaoToken 支持的模型名一致。回到模型对话页面确认可用模型再填进配置。报错四OAuth 相关错误如果你在 Claude Code 里看到OAuth token expired或者Please run claude login to authenticate定位方法这说明 Claude Code 还在尝试用 OAuth 方式认证而不是用你配置的 API Key。Claude Code 的认证优先级是OAuth token API Key。如果你之前登录过官方账号OAuth token 还在缓存里就会覆盖你的 API Key 配置。修复步骤先执行claude logout清除 OAuth 缓存然后确认~/.claude/settings.json里的ANTHROPIC_AUTH_TOKEN和ANTHROPIC_BASE_URL配置正确再重启 Claude Code。如果还是不行检查是否有其他环境变量比如 shell 的.bashrc或.zshrc里设置了ANTHROPIC_API_KEY它可能会覆盖 settings.json 里的配置。报错五后台任务超时但主循环没收到通知这个不是报错而是行为异常。你发现后台任务明明已经跑完了但模型一直没收到background-results。定位方法检查drain_notifications()是否在agent_loop()开头被调用。如果这段代码被注释掉了或者位置放错了比如放在了 LLM 调用之后通知就不会被注入。修复步骤确认agent_loop()的while True循环里第一件事就是notifs BG.drain_notifications()然后再调用client.messages.create()。顺序不能反。报错六并发任务互相干扰你启动多个后台任务后发现结果串了或者某个任务的结果被覆盖。定位方法检查_notification_queue的写入是否加了锁。_execute()里往队列 append 的时候必须在with self._lock:保护下进行。如果漏了锁多线程同时写队列就会出问题。修复步骤确认_execute()里的这段with self._lock: self._notification_queue.append({ task_id: task_id, status: status, command: command[:80], result: (output or (no output))[:500], })锁不能省。这是 s08 并发安全的基础。6. 语义一致 CTA把 s08 的并发能力真正用起来s08 的 Background Tasks 机制本身不复杂核心就是三件事background_run把慢命令丢到后台线程并立即返回 task_id_notification_queue暂存完成结果drain_notifications()在下一次 LLM 调用前统一注入。但要让这套机制稳定跑起来Base URL 的配置是绕不过去的一步。如果你在排障过程中遇到 401、连接失败、模型不存在这类问题优先去 API Keys 页面重新确认 Key 和模型 IDhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档里有完整的端点和参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你想先手动验证某个模型在 TaoToken 上是否可用直接去模型对话页面发一条消息最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。确认可用后再填进 s08 的ANTHROPIC_MODEL。如果你打算长期跑 s08 这类并发 Agent 实验或者把 learn-claude-code 的后续章节s09 Agent Teams 等也一起跟下去Coding Plan 会比按量付费更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对的就是这种高频、长时运行的编码场景。配置改完之后建议先用文档里的三个 prompt 各跑一遍观察后台任务的启动、完成、通知注入三个阶段的时序。特别是第三个 promptRun pytest in the background and keep working on other things它最接近真实工程场景——测试在后台跑主循环继续处理其他任务等测试完成后结果自动汇合。这个流程跑通了s08 的并发能力才算真正落地。

Learn-Claude-Code 笔记 | Concurrency | s08 Background Tasks 的 Base URL 改到 TaoToken 实践

相关推荐

9.9包月+OpenCode教程：开源编程神器接入TaoToken实战

UltraEdit 正则表达式实战：删除包含某个字符串的所有行（含 TaoToken 配置示例）

deadline前两周，我靠这个工具把论文从大纲补到终稿

更多资讯

SAP销售订单与发票利润中心替代实战：UserExit增强配置与代码解析

docker-selenium 镜像标签生成指南：解读 tag_and_push_browser_images.sh 与 Chrome 112 发布记录

基于SpringBoot+Vue的电子竞技青训系统设计与实现

从单体到可扩展：后台管理系统架构演进与模块化实践

基于微信小程序的中学德育实践活动管理系统设计与实现

Linux 内核揭秘：用户空间程序的启动过程——从 `_start` 到 `main` 的完整调用链

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？