1. 从零构建 Code Agent 的真实起点：为什么“能跑”和“能稳”是两回事
很多人第一次接触 Claude Code 这类工具时，最直观的感受是“它怎么什么都能干”。但当你真正动手从零构建一个 Code Agent，才会发现核心难点从来不是让模型开口说话，而是让它稳定地完成“读文件、搜代码、改代码、跑命令”这一整套动作。我试过直接拿一个通用对话模型套上几个工具函数就开跑，结果前几轮还挺像样，任务一复杂就开始胡言乱语——要么把文件路径写错，要么在同一个报错上反复撞墙。
这个场景下，你需要的是一个可对话、可执行工具、可追溯的本地 Code Agent。它至少要具备四个能力：第一，能理解自然语言需求并拆解成步骤；第二，能调用文件系统、搜索、终端等工具去仓库里找证据；第三，能输出可落地的补丁并安全执行；第四，能在长对话中保持上下文不腐烂。而这一切的底座，是模型调用通道的稳定性。
我选择用 TaoToken 作为统一 Key 接入层，原因很直接：本地开发 Agent 时，最烦的就是在多个模型供应商之间来回切换配置。TaoToken 提供统一的 API 入口，兼容 OpenAI 风格的 Function Calling 协议，这意味着我的 Agent 主循环不需要为每个模型写适配层。你可以在 https://taotoken.net/api 拿到兼容接口，配合 https://taotoken.net/api-keys 生成的 Key 就能直接调用。
这一章先不急着写代码，而是把整个链路的骨架讲清楚。一个 Code Agent 的最小闭环包含五个模块：LLM 调用层、工具注册中心、ReAct 主循环、上下文管理器、执行器。LLM 调用层负责把消息和工具 Schema 发给模型；工具注册中心维护所有可调用工具的 JSON Schema；ReAct 主循环负责“模型输出 tool_calls → 执行工具 → 回填结果 → 继续推理”这个循环；上下文管理器负责截断、压缩、分层；执行器负责把模型生成的补丁安全落盘。
很多教程一上来就让你写几百行代码，但真正卡住新手的往往是环境配置和协议对齐。比如 Function Calling 要求模型返回结构化的 tool_calls，而不是自由文本。如果你用的是字符串解析那套 ReAct，模型多说一句“好的，我来帮你”就会导致正则匹配失败。所以从第一天起，我就建议你直接走 Function Calling 协议，把“模型输出”当成结构化数据来处理，而不是当成作文来批改。
还有一个容易被忽略的点：工具返回结果必须统一格式。如果 Read 工具返回纯文本，Grep 工具返回 JSON，模型就得花额外精力去“理解”每个工具的输出结构。更好的做法是定义一个标准信封，包含 status、data、text、stats 四个字段。模型看到 status 就知道成功还是失败，看到 data 就能直接取结构化数据，看到 text 就能拿到人类可读的摘要。这个设计在后面做上下文压缩时会省下大量精力。
最后说说为什么强调“从零”。因为只有你自己搭一遍，才会真正理解 Claude Code 这类产品在工程上做对了什么。它不是模型更聪明，而是工具边界更清晰、调用协议更严格、上下文治理更精细。你把这些工程细节补齐，哪怕用同一个模型，Agent 的稳定性也会有肉眼可见的提升。
2. TaoToken 统一 Key 接入前置：把模型调用通道先跑通
在写 Agent 主循环之前，必须先把模型调用通道跑通。这一步看起来简单，但实际踩坑的人不少。TaoToken 的接入方式兼容 OpenAI 的 Chat Completions 接口，所以你不需要引入额外的 SDK，直接用 openai 这个 Python 包就能调用。关键是把 base_url 指向 https://taotoken.net/api，而不是默认的 OpenAI 地址。
先安装依赖。我建议用虚拟环境，避免和系统里的包冲突：
python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install openai httpx然后配置环境变量。不要把 Key 硬编码在代码里，这是基本的安全习惯：
export TAOTOKEN_API_KEY="你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"如果你用的是 Windows PowerShell，换成$env:TAOTOKEN_API_KEY="你的Key"。配置完成后，写一个最小调用脚本验证通道是否通畅：
import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) resp = client.chat.completions.create( model="claude-sonnet-4-20250514", messages=[{"role": "user", "content": "用一句话说明什么是 Function Calling"}], ) print(resp.choices[0].message.content)如果这一步能打印出正常回答，说明 Key 和通道都没问题。接下来要验证的是 Function Calling 是否可用。这是 Code Agent 的核心能力，必须提前确认。写一个带工具定义的请求：
tools = [ { "type": "function", "function": { "name": "read_file", "description": "读取指定路径的文件内容", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "文件相对路径"} }, "required": ["path"], }, }, } ] resp = client.chat.completions.create( model="claude-sonnet-4-20250514", messages=[{"role": "user", "content": "帮我读取 README.md"}], tools=tools, tool_choice="auto", ) msg = resp.choices[0].message print("tool_calls:", msg.tool_calls)如果返回的 message 里包含 tool_calls 字段，并且 function.name 是 read_file，说明 Function Calling 链路正常。这一步非常关键，因为后面整个 Agent 主循环都依赖这个协议。如果这里返回的是纯文本而不是 tool_calls，说明模型或通道不支持结构化调用，需要换模型或检查参数。
关于模型选择，TaoToken 支持多种模型 ID。对于 Code Agent 场景，我建议优先选支持长上下文和 Function Calling 的模型。你可以在 https://taotoken.net/models 查看可用模型列表。实际测试下来，Claude 系列在工具调用稳定性上表现不错，适合作为主循环的推理模型。
还有一个细节：超时和重试。本地开发时网络波动很常见，建议给 client 配置合理的超时时间，并加一层简单的重试逻辑：
client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], timeout=60.0, max_retries=2, )这样即使偶发超时，Agent 也不会直接崩溃。把这一层封装成一个 LLMClient 类，后面主循环里只调用这个类的方法，方便统一管理。
3. 可复制配置：Agent 主循环与工具注册的完整骨架
这一章给出可以直接复制的配置和代码骨架。先定义项目结构，建议这样组织：
my_code_agent/ ├── agent/ │ ├── __init__.py │ ├── llm_client.py # 模型调用封装 │ ├── registry.py # 工具注册中心 │ ├── loop.py # ReAct 主循环 │ └── context.py # 上下文管理 ├── tools/ │ ├── __init__.py │ ├── read.py │ ├── grep.py │ └── edit.py ├── config/ │ └── settings.json └── main.py先写工具注册中心。它的职责是维护工具名到函数的映射，并自动生成 JSON Schema：
# agent/registry.py import json from typing import Callable, Any class ToolRegistry: def __init__(self): self._tools: dict[str, dict] = {} def register(self, name: str, description: str, parameters: dict, func: Callable): self._tools[name] = { "schema": { "type": "function", "function": { "name": name, "description": description, "parameters": parameters, }, }, "func": func, } def get_schemas(self) -> list[dict]: return [t["schema"] for t in self._tools.values()] def execute(self, name: str, args: dict) -> Any: if name not in self._tools: return {"status": "error", "text": f"未知工具: {name}"} try: return self._tools[name]["func"](**args) except Exception as e: return {"status": "error", "text": f"工具执行失败: {e}"}接着写一个 Read 工具作为示例。注意返回统一信封：
# tools/read.py import os def read_file(path: str, max_lines: int = 500) -> dict: if not os.path.exists(path): return {"status": "error", "text": f"文件不存在: {path}"} with open(path, "r", encoding="utf-8", errors="ignore") as f: lines = f.readlines() truncated = len(lines) > max_lines content = "".join(lines[:max_lines]) return { "status": "partial" if truncated else "success", "data": {"content": content, "total_lines": len(lines)}, "text": f"读取 {path}，共 {len(lines)} 行" + ("（已截断）" if truncated else ""), }然后在 main.py 里注册工具并启动主循环：
# main.py import os from openai import OpenAI from agent.registry import ToolRegistry from tools.read import read_file client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) registry = ToolRegistry() registry.register( name="read_file", description="读取指定路径的文件内容", parameters={ "type": "object", "properties": { "path": {"type": "string", "description": "文件相对路径"}, "max_lines": {"type": "integer", "description": "最大读取行数"}, }, "required": ["path"], }, func=read_file, ) def run_agent(user_input: str, max_steps: int = 10): messages = [ {"role": "system", "content": "你是一个代码助手，可以调用工具读取文件。"}, {"role": "user", "content": user_input}, ] for step in range(max_steps): resp = client.chat.completions.create( model="claude-sonnet-4-20250514", messages=messages, tools=registry.get_schemas(), tool_choice="auto", ) msg = resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: args = json.loads(call.function.arguments) result = registry.execute(call.function.name, args) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False), }) return "达到最大步数限制" if __name__ == "__main__": print(run_agent("读取 README.md 并总结内容"))这段代码就是 Agent 的最小闭环。你可以直接复制运行，只要环境变量配好，就能看到模型调用 read_file 工具并返回结果。注意 messages 里 assistant 消息必须原样 append，tool 消息必须带 tool_call_id，这是 Function Calling 协议的硬要求。
如果你用的是 Claude Code 类工具做本地开发，可能还会涉及 settings.json 配置。比如在项目根目录放一个 config/settings.json：
{ "model": "claude-sonnet-4-20250514", "base_url": "https://taotoken.net/api", "max_steps": 20, "tool_output_max_lines": 2000, "tool_output_max_bytes": 51200 }这个配置文件后面可以扩展成支持 MCP 服务器列表、Skills 目录等。把配置和代码分离，改参数时不用动主逻辑。
4. 验证请求与成功结果：一次端到端工具调用实测
配置写完后，必须做一次端到端验证。我设计一个最小但完整的测试场景：让 Agent 读取当前目录下的一个 Python 文件，统计函数数量，并输出结果。这个任务需要模型调用 read_file 工具，拿到内容后自己分析，最后给出答案。
准备一个测试文件 demo.py：
def foo(): pass def bar(): return 1 class Baz: def method(self): pass然后运行 Agent：
print(run_agent("读取 demo.py，告诉我里面有几个函数定义"))预期流程是这样的：第一轮模型返回 tool_calls，调用 read_file，参数 path 为 demo.py。你的代码执行工具，把文件内容回填到 messages。第二轮模型拿到内容后，不再调用工具，直接输出类似“demo.py 中有 2 个顶层函数定义：foo 和 bar，另外 Baz 类里有一个 method 方法”的回答。
如果这一步成功，说明整条链路是通的：TaoToken 通道正常、Function Calling 协议正常、工具注册和执行正常、消息回填正常。这是从零构建 Code Agent 的第一个里程碑。
接下来验证多步调用。让 Agent 先列目录再读文件：
print(run_agent("先看看当前目录有哪些文件，然后读取 main.py 的前 20 行"))这个任务需要模型连续调用两次工具。第一次可能是 list_dir，第二次是 read_file。你要观察 messages 数组是否正确累积，tool_call_id 是否一一对应。如果模型在第二轮忘记之前的工具结果，说明消息回填有问题。
实测下来，最容易出错的点是 arguments 的 JSON 解析。模型有时会返回带换行或多余空格的 JSON 字符串，直接 json.loads 可能失败。建议加一层容错：
def safe_parse_args(raw: str) -> dict: try: return json.loads(raw) except json.JSONDecodeError: # 尝试去掉尾部多余字符 raw = raw.strip().rstrip("}") raw += "}" return json.loads(raw)还有一个验证点是工具返回的 status 字段。如果 read_file 返回 partial，模型应该知道内容被截断了。你可以在系统提示里加一句：“如果工具返回 status 为 partial，说明内容被截断，必要时可以分段读取。”这样模型的行为会更合理。
成功结果的标准是什么？不是模型回答得多漂亮，而是这三件事同时成立：第一，工具被正确调用且参数合法；第二，工具结果被完整回填且 tool_call_id 匹配；第三，模型基于工具结果给出了符合事实的回答。三者缺一，链路就不算通。
5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth
这一章对照真实报错来排查。第一个高频错误是 401 Unauthorized。典型报错信息是Error code: 401 - {'error': {'message': 'Invalid API key'}}。原因通常是环境变量没生效，或者 Key 复制时带了空格。排查步骤：先在终端执行echo $TAOTOKEN_API_KEY确认变量存在；然后检查代码里读取的变量名是否一致；最后确认 base_url 是 https://taotoken.net/api 而不是其他地址。如果用的是 .env 文件，记得用 python-dotenv 加载。
第二个错误是local proxy failed或连接超时。这类报错通常出现在网络环境不稳定时。排查方向：先确认能否直接访问 https://taotoken.net/api，可以用 curl 测试：
curl -X POST https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}]}'如果 curl 能通但 Python 不通，检查是否有系统级代理设置干扰。另外把 timeout 调大一些，本地开发时 60 秒比较稳妥。
第三个错误是reading 'choices'或KeyError: 'choices'。这通常是因为返回体不是标准的 Chat Completions 格式，或者请求被拦截返回了错误页。排查方法：在调用后先打印完整 resp，看结构对不对。如果 resp 里没有 choices，可能是模型 ID 写错了，或者请求体格式有问题。确认 model 字段用的是 TaoToken 支持的模型 ID，可以在 https://taotoken.net/models 查。
第四个错误是 OAuth 相关报错，比如OAuth token expired或invalid_grant。如果你用的是 Claude Code 类客户端，可能会遇到 OAuth 认证问题。这时候需要检查客户端的认证配置。对于 Claude Code 接入，推荐使用 API Key 方式而不是 OAuth，配置三件套：Base URL 填 https://taotoken.net/api，API Key 填你的 Key，Model ID 填支持的模型。如果你在用 CC Switch 或 Cline MCP，同样需要确认这三项配置一致。
还有一个隐蔽错误是工具调用死循环。模型反复调用同一个工具，每次都返回相同结果。这通常是因为工具返回的 text 里没有明确告诉模型“已经完成”或“没有更多内容”。解决办法是在工具返回里加状态提示，比如搜索无结果时返回{"status": "success", "text": "未找到匹配项，建议换关键词"}，而不是空字符串。
最后提醒一点：如果报错信息里出现tool_call_id mismatch，说明你在回填 tool 消息时用的 id 和 assistant 消息里的 id 不一致。检查代码里是否用了call.id而不是自己生成的 id。这个错误在手动拼接 messages 时很常见。
6. 语义一致 CTA：把统一 Key 接入变成长期可用的开发习惯
走到这里，你已经有了一个能跑通 Function Calling 的 Code Agent 骨架。但要让它在真实项目里长期可用，还需要把模型调用通道固化下来。TaoToken 的统一 Key 接入价值就在这里：你不需要在每次换模型时重写调用层，只需要改一个 model 字段。对于长期编码和 Agent 开发场景，可以考虑 Coding Plan，把常用模型和额度统一管理，减少反复配置的成本。
如果你在排查接入问题时需要对照文档，接入文档里有完整的参数说明和示例。验证模型是否可用时，可以直接用模型对话做快速测试。而 API Keys 页面则是生成和管理 Key 的入口。这三个入口配合使用，基本覆盖了从调试到上线的全流程。
回到 Agent 本身，下一步可以扩展的方向很多：把 Read、Grep、Edit 做成原子工具链，加上乐观锁防止并发修改；引入统一截断机制，把超长工具输出落盘保存；用 Summary 压缩旧历史，避免长对话上下文腐烂；加一层 TraceLogger，把每一步 tool_call 和 tool_result 记录下来，方便复盘。这些工程细节才是 Code Agent 从“能跑”到“能稳”的关键。
我自己的习惯是每加一个新工具，就先写一个最小验证脚本，确认 Function Calling 链路正常后再集成到主循环。这样出问题时排查范围小，不会一上来就面对几百行代码。你也可以把这个习惯保持下去，Agent 开发本质上是一个不断缩小不确定性的过程。
