1. Claude code agent 到底由哪些东西组成：一次把组件拆开看
很多人第一次接触 Claude code agent，会以为它就是一个“会写代码的模型”。真跑起来才发现，它更像一支小型施工队：有人负责看图纸，有人负责搬砖，有人负责验收，还有人负责记账。模型只是那个“会思考的工头”，真正让它能干活的，是围绕它搭起来的一整套组件。
我理解的 Claude code agent，核心可以拆成六层：工具与执行循环、规划与协调、子 agent、技能系统、任务系统、内存与上下文管理，再往外还有并发后台任务、协作 agent 团队、自主 agent、worktree 工作隔离。这些名字听着唬人，其实每一层都在解决一个具体问题——上下文太胖、进度会丢、任务没依赖、多个 agent 互相踩脚。
这篇文章不打算只讲概念。我会从“统一 Key / API 通道”这个视角切入，把每个组件的职责讲清楚，然后给出可复制的配置片段和验证步骤。你跟着做，能亲手跑通一个最小 agent 循环，再逐步理解每个模块为什么存在。适合想搞懂 agent 架构、又不想只停留在 PPT 层面的开发者。
先说结论：agent 的组成不是越多越好，而是每加一个组件，都要对应一个真实痛点。下面按“从最小可用到逐步增强”的顺序拆。
2. TaoToken 统一 Key 前置：把 API 通道先打通
在拆组件之前，得先把“模型调用”这条通道打通。Claude code agent 的所有组件，最终都要通过一个 API 通道去调用模型。如果每个组件、每个子 agent、每个队友都各自配一套 Key，管理会非常乱。所以我习惯用一个统一 Key 的方式，把 Base URL、Key、Model ID 三件套集中管理。
TaoToken 在这里扮演的就是统一入口的角色。官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置的时候别写错。
为什么强调“统一 Key”？因为后面你会看到，子 agent 要新开上下文、队友 agent 要独立 loop、后台任务要并发跑，如果每个都单独配 Key，改一次模型就得改十几处。统一 Key 的好处是：所有组件共享同一个 Base URL 和 Key，只在需要时切换 Model ID。
先拿 Key。打开 https://taotoken.net/api-keys ，创建一个 API Key，复制保存。然后确认你要用的模型 ID，可以在 https://taotoken.net/models 查。我实测下来，Claude 系列在 coding 场景表现稳定，适合做 agent 的主模型。
拿到三件套后，建议用环境变量管理，别硬编码进代码：
export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_MODEL="claude-sonnet-4-5"如果你用 Claude Code 这类工具，配置方式不太一样。Claude Code 读取的是 settings 文件，路径通常在~/.claude/settings.json。可以这样写：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }注意这里的环境变量名是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，不是随便起的。Claude Code 内部按这套变量名读取。如果你用的是 Codex 类工具，它读的是~/.codex/auth.json，结构类似：
{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的key" }三件套的核心就是：Base URL 指向统一通道，Key 用同一个，Model ID 按场景选。配好之后，先别急着写 agent，用一条最简单的请求验证通道是否通。
3. 可复制配置：最小 agent 循环 + 工具分发
通道打通后，我们来看 agent 最核心的组件：工具与执行循环。一个最简单的 agent，本质就是“一个 while 循环 + 一组工具”。用户消息进来，创建带工具定义的模型调用，检查是否要继续调工具，逐个执行工具并把结果塞回消息，循环直到模型不再调工具。
先写最小循环。用 Python 的 anthropic SDK：
import os from anthropic import Anthropic client = Anthropic( base_url=os.environ["TAOTOKEN_BASE_URL"], api_key=os.environ["TAOTOKEN_API_KEY"], ) MODEL = os.environ["TAOTOKEN_MODEL"] WORKDIR = os.path.abspath("./workspace") def agent_loop(query): messages = [{"role": "user", "content": query}] while True: response = client.messages.create( model=MODEL, system="You are a coding agent.", messages=messages, tools=TOOLS, max_tokens=8000, ) messages.append({"role": "assistant", "content": response.content}) if response.stop_reason != "tool_use": return response.content results = [] for block in response.content: if block.type == "tool_use": handler = TOOL_HANDLERS.get(block.name) output = handler(**block.input) if handler else f"Unknown tool: {block.name}" results.append({ "type": "tool_result", "tool_use_id": block.id, "content": str(output)[:50000], }) messages.append({"role": "user", "content": results})这段代码就是 agent 的心脏。但只有 bash 一个工具时，所有操作都走 shell，cat截断不可预测，sed遇到特殊字符就崩，而且每次 bash 调用都是不受约束的安全面。所以第二步是加专用工具，并做路径沙箱。
路径沙箱的核心是把用户传进来的相对路径拼到工作目录后，再 resolve 成绝对路径，检查是否还在工作目录内：
from pathlib import Path def safe_path(p: str) -> Path: path = (Path(WORKDIR) / p).resolve() if not path.is_relative_to(WORKDIR): raise ValueError(f"Path escapes workspace: {p}") return path def run_read(path: str, limit: int = None) -> str: text = safe_path(path).read_text() lines = text.splitlines() if limit and limit < len(lines): lines = lines[:limit] return "\n".join(lines)[:50000]然后建一个分发图（dispatch map），把工具名映射到处理函数：
TOOL_HANDLERS = { "bash": lambda **kw: run_bash(kw["command"]), "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")), "write_file": lambda **kw: run_write(kw["path"], kw["content"]), "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]), }这里的**kw表示接收任意数量的关键字参数并打包成字典。循环里按名称查找处理函数，找不到就返回 Unknown tool。对比一下：加工具前只有 1 个 bash，硬编码调用；加工具后有 4 个工具，用字典分发，还多了路径安全。agent loop 本身不变——这就是好架构的特征，扩展点集中在工具层，循环保持稳定。
工具定义TOOLS也要同步写，每个工具要有 name、description、input_schema。description 写清楚，模型才知道什么时候用哪个工具。
4. 验证请求：跑通一次真实工具调用
配置写好了，得验证。先跑一个最简单的请求，确认通道和模型都正常：
resp = client.messages.create( model=MODEL, max_tokens=200, messages=[{"role": "user", "content": "用一句话说明什么是 agent loop"}], ) print(resp.content[0].text)如果这一步报 401，说明 Key 或 Base URL 有问题，先回去检查环境变量。如果正常返回文本，说明通道通了。
接着验证工具调用。给 agent 一个明确任务：“读取 workspace 下的 README.md，统计有多少行”。预期行为是：模型先返回一个tool_use块，name 是read_file，input 里带 path；你的循环执行run_read，把结果作为tool_result塞回；模型再基于结果给出答案。
跑通后你会看到类似这样的过程：
[assistant] tool_use: read_file {"path": "README.md"} [tool_result] 前 50000 字符内容... [assistant] 这个文件共有 42 行。再验证路径沙箱。故意传一个越界路径：
run_read("../../etc/passwd")预期抛出ValueError: Path escapes workspace。这一步很重要，它证明你的工具层有安全边界，不是裸奔的 shell。
验证子 agent 时，可以给父 agent 一个 task 工具，让它“新开一个子 agent 去统计 workspace 下所有 .py 文件的行数”。子 agent 以messages=[]启动，跑自己的循环，最后只把摘要返回给父 agent。父 agent 的上下文里只多了一条 tool_result，而不是子 agent 跑过的几十次工具调用记录。这就是上下文隔离的价值。
验证技能系统时，建一个skills/git/SKILL.md，带 YAML frontmatter：
--- name: git description: Git workflow helpers --- Step 1: 检查当前分支... Step 2: 提交前先跑测试...系统提示里只放技能目录（约 100 token/skill），模型需要时调load_skill("git")，才把完整正文（约 2000 token）注入。这样 10 个技能不会一上来就吃掉 20000 token。
5. 本篇常见错排查：401、local proxy failed、reading choices
跑 agent 的过程中，报错基本集中在几个地方。我按真实遇到的顺序列一下。
401 Unauthorized。最常见。原因通常是 Key 没读到、Base URL 写错、或者环境变量名不对。检查三点：TAOTOKEN_API_KEY是否真的 export 了；TAOTOKEN_BASE_URL是否是https://taotoken.net/api（注意结尾没有多余斜杠）；Claude Code 场景下变量名是否是ANTHROPIC_API_KEY而不是TAOTOKEN_API_KEY。改完记得重启终端或重新加载 settings。
local proxy failed。这个报错通常出现在工具链试图走本地代理时。检查你的环境里有没有残留的HTTP_PROXY/HTTPS_PROXY变量，有的话先 unset。另外确认 Base URL 直接指向https://taotoken.net/api，不要中间再套一层本地转发。
reading choices 相关报错。这类错误一般出现在解析模型响应时，比如response.content为空、或者stop_reason不是预期值。排查方向：确认max_tokens没设太小导致响应被截断；确认模型 ID 拼写正确；打印完整response看结构。如果是子 agent 场景，检查子 agent 的messages是否以[{"role": "user", ...}]正确初始化。
OAuth 相关报错。有些工具默认走 OAuth 登录流程，如果你用的是 API Key 模式，需要在配置里显式关闭 OAuth。Claude Code 场景下确认 settings 里没有冲突的登录配置；Codex 场景下确认auth.json里是 API Key 而不是 OAuth token。
工具调用死循环。模型反复调同一个工具，通常是工具返回结果里没有足够信息让它判断“已完成”。检查tool_result内容是否被截断得太狠，或者 description 是否写得太模糊。给工具加一个明确的成功/失败标识会有帮助。
上下文爆炸。跑长任务时messages数组越来越大，最后超限。这时候需要上下文压缩：第一层 micro_compact，把超过 3 轮的旧 tool_result 替换成占位符；第二层 auto_compact，token 超阈值时把完整对话存盘，让模型做摘要，用摘要替换所有消息；第三层是模型主动调 compact 工具。三层配合，活跃上下文始终可控。
排查的核心思路是：先确认通道（401 类），再确认工具层（路径、参数），最后确认循环逻辑（stop_reason、消息结构）。大部分问题都在前两层。
6. 从组件到协作：任务系统、团队与 worktree 隔离
前面拆的是单个 agent 的组件。当任务变复杂，单 agent 就不够了，需要任务系统、协作团队和工作隔离。
任务系统的核心是把内存里的扁平清单升级成持久化到磁盘的任务图。每个任务一个 JSON 文件，有状态、前置依赖blockedBy和后置依赖blocks。任务图随时回答三个问题：什么可以做（pending 且 blockedBy 为空）、什么被卡住（等前置完成）、什么做完了（completed 并自动解锁后续）。完成任务时自动把它的 ID 从其他任务的 blockedBy 里移除，这就是依赖解除。
协作 agent 团队的核心是：每个队友一个独立 loop，用磁盘上的团队配置和收件箱互相传消息。config.json是花名册，inbox/*.jsonl是邮箱，发消息就是往对方邮箱追加一行 JSON，收消息就是读全部再清空。队友生命周期是 spawn → WORKING → IDLE → WORKING → SHUTDOWN。关机协议和计划审批协议共用同一个状态机：发起方生成 request_id，接收方 approve/reject，状态从 pending 走到 approved 或 rejected。
自主 agent 在队友基础上加了 IDLE 阶段：空闲时轮询收件箱和任务看板，发现未认领任务就自动认领。还有一个细节是身份重注入——上下文压缩后 agent 可能忘了自己是谁，所以在消息过短时在开头插入身份块。
worktree 工作隔离解决的是“多个 agent 同时改同一个文件”的问题。控制面在.tasks/，执行面在.worktrees/。每个任务绑定一个独立 git worktree 目录，用任务 ID 关联。创建 worktree 时自动把任务推进到 in_progress，收尾时worktree_remove(name, complete_task=True)一个调用搞定拆除加完成。每个生命周期步骤写入events.jsonl，崩溃后可以从磁盘状态重建现场。
把这些组件串起来看，Claude code agent 的组成就清晰了：工具与循环是心脏，规划与任务是大脑，子 agent 和技能是手脚，内存管理是呼吸，并发和团队是协作，worktree 是隔离。统一 Key 则是贯穿所有组件的血管。想动手的话，可以从 API Keys 页面拿 Key，再对着接入文档把最小循环跑起来；想验证模型表现，可以直接在模型对话里试；如果要做长期编码或 Agent 项目，Coding Plan 会更省心。
