1. 为什么你的 Agent 只会“踹一下动一下”很多人第一次写 AI Agent代码长这样读一行输入调一次大模型接口打印结果结束。跑起来没问题但它本质上是个“问答机”不是 Agent。真正的 Agent 要能自己判断“我现在该说话还是该去调个工具还是该停下来”这个判断动作会一轮一轮重复直到任务完成。这个重复结构就是 Agent 循环Agent Loop。claw0 这个项目把 Agent 网关拆成 10 节课第一课 s01_agent_loop.py 只做一件事把while True加stop_reason这个最小闭环跑通。别小看它后面加工具调用、会话持久化、心跳、定时任务、IM 通道路由全都是在不改动这个循环骨架的前提下往上叠层。换句话说第一课没吃透后面九节课你都是在抄代码而不是在理解系统。这篇面向想搞明白“Agent 到底怎么自主决策”的开发者。我会带你把环境配好、把 settings 骨架写出来、把循环控制逻辑讲清楚最后实打实跑一次完整循环验证让你看到模型在end_turn和tool_use两个分支上分别怎么走。全程可复制不需要你提前懂 Anthropic SDK。2. 前置准备TaoToken 接入与 claw0 环境2.1 为什么用 TaoToken 做模型接入层claw0 的循环代码里模型客户端是通过base_url指向一个兼容 Anthropic 协议的服务。你可以把它理解成“模型插座”循环逻辑是电器插座负责把请求送到具体模型。TaoToken 提供的就是这样一个统一接入层你换模型只需要改MODEL_ID和对应的 key循环代码一行不用动。对第一课来说你只需要两样东西一个可用的 API Key一个模型 ID。Key 在控制台生成模型 ID 按你实际想调的模型填。2.2 拿到 API Key打开 TaoToken 控制台进入 API Keys 页面新建一个 key。建议命名带上用途比如claw0-s01方便后面轮换时辨认。生成后立刻复制保存页面刷新后就不再完整显示。注意key 只存在本地.env文件里不要写进代码、不要提交到 git。claw0 的.gitignore默认忽略.env但你自己新建文件时要确认这一点。2.3 克隆 claw0 并建虚拟环境git clone https://github.com/shareAI-lab/claw0.git cd claw0 python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -r requirements.txt虚拟环境这一步别省。claw0 依赖anthropic、python-dotenv等包全局装容易和你机器上其他项目的版本打架。激活后命令行前面会出现(.venv)看到它就说明解释器选对了。2.4 写 settings.json 与 .env 骨架claw0 用.env管密钥用一份配置骨架管模型和运行参数。先复制模板cp .env.example .env然后编辑.env填入你的接入信息ANTHROPIC_API_KEY你的TaoToken密钥 ANTHROPIC_BASE_URLhttps://taotoken.net/api MODEL_ID你的模型ID这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址SDK 会把请求发到这里再由它路由到具体模型。MODEL_ID填你在控制台看到的模型标识。如果你想把运行参数也结构化可以额外建一个settings.json第一课只需要最简结构{ model: 你的模型ID, max_tokens: 8096, system_prompt: You are a helpful AI assistant. Answer questions directly., loop: { max_turns: 20, exit_keywords: [quit, exit] } }max_turns是循环的安全阀防止模型陷入死循环时无限调用。第一课虽然用不到工具但把这个字段先留出来后面加工具调用时直接复用。3. 可复制配置Agent 循环的最小骨架3.1 循环的三个不变量claw0 第一课反复强调三件事我把它拆成你能记住的说法第一messages[]是唯一的状态。每次调 API模型看到的都是这个完整数组不是单条消息。所以对话能记住上下文靠的就是这个数组在循环外累积。第二stop_reason是唯一的决策点。模型每次响应都会带一个stop_reason你只根据它决定下一步。end_turn表示模型说完了打印文本tool_use表示模型想调工具去执行再把结果塞回去。第三循环结构永远不变。后面加工具、加会话、加路由改的是分支里的处理逻辑while True加stop_reason这个骨架不动。3.2 核心循环代码把下面这段存成s01_agent_loop.py它和 claw0 官方版本结构一致我加了中文注释方便你对照import os import sys from pathlib import Path from dotenv import load_dotenv from anthropic import Anthropic # 加载 .envoverrideTrue 让本地配置覆盖系统环境变量 load_dotenv(Path(__file__).resolve().parent.parent.parent / .env, overrideTrue) MODEL_ID os.getenv(MODEL_ID, claude-sonnet-4-20250514) client Anthropic( api_keyos.getenv(ANTHROPIC_API_KEY), base_urlos.getenv(ANTHROPIC_BASE_URL) or None, ) SYSTEM_PROMPT You are a helpful AI assistant. Answer questions directly. CYAN \033[36m GREEN \033[32m YELLOW \033[33m DIM \033[2m RESET \033[0m BOLD \033[1m def colored_prompt() - str: return f{CYAN}{BOLD}You {RESET} def print_assistant(text: str) - None: print(f\n{GREEN}{BOLD}Assistant:{RESET} {text}\n) def print_info(text: str) - None: print(f{DIM}{text}{RESET}) def agent_loop() - None: messages: list[dict] [] print_info( * 60) print_info( claw0 | Section 01: Agent 循环) print_info(f Model: {MODEL_ID}) print_info( 输入 quit 或 exit 退出. CtrlC 同样有效.) print_info( * 60) print() while True: # 1. 收集输入 try: user_input input(colored_prompt()).strip() except (KeyboardInterrupt, EOFError): print(f\n{DIM}再见.{RESET}) break if not user_input: continue if user_input.lower() in (quit, exit): print(f{DIM}再见.{RESET}) break # 2. 追加到历史 messages.append({role: user, content: user_input}) # 3. 调用 API try: response client.messages.create( modelMODEL_ID, max_tokens8096, systemSYSTEM_PROMPT, messagesmessages, ) except Exception as exc: print(f\n{YELLOW}API Error: {exc}{RESET}\n) messages.pop() # 回滚脏数据 continue # 4. 根据 stop_reason 分支 if response.stop_reason end_turn: assistant_text for block in response.content: if hasattr(block, text): assistant_text block.text print_assistant(assistant_text) messages.append({role: assistant, content: response.content}) elif response.stop_reason tool_use: print_info([stop_reasontool_use] 本节没有可用工具.) print_info(参见 s02_tool_use.py 了解工具支持.) messages.append({role: assistant, content: response.content}) else: print_info(f[stop_reason{response.stop_reason}]) assistant_text for block in response.content: if hasattr(block, text): assistant_text block.text if assistant_text: print_assistant(assistant_text) messages.append({role: assistant, content: response.content}) def main() - None: if not os.getenv(ANTHROPIC_API_KEY): print(f{YELLOW}Error: ANTHROPIC_API_KEY 未设置.{RESET}) print(f{DIM}将 .env.example 复制为 .env 并填入你的 key.{RESET}) sys.exit(1) agent_loop() if __name__ __main__: main()3.3 关键参数对照参数作用第一课建议值max_tokens单次响应最大 token 数8096system系统提示词设定一次全程生效简短明确messages累积的对话历史循环外定义stop_reason决策依据只认 end_turn / tool_usemax_turns循环安全阀settings.json20system提示词相当于给模型一本工作手册设一次它整个对话都遵守。messages必须 user 和 assistant 交替出现且永远以 user 开头这是接口的硬性格式要求写错了会直接报错。4. 验证请求跑通第一个 Agent 闭环4.1 启动脚本python sessions/zh/s01_agent_loop.py如果你把代码放在项目根目录直接python s01_agent_loop.py也行。启动后你会看到 claw0 | Section 01: Agent 循环 Model: 你的模型ID 输入 quit 或 exit 退出. CtrlC 同样有效. You 4.2 多轮对话验证上下文输入第一句You 法国的首都是哪里? Assistant: 法国的首都是巴黎。再输入第二句You 它的人口是多少? Assistant: 巴黎市区人口约 210 万大巴黎都会区约 1200 万。注意第二句里你根本没提“巴黎”但模型答对了。这就是messages[]累积的效果——每次请求都把完整历史发给模型它自然记得上一轮说的“法国”。如果你把messages定义在循环内部第二句就会答非所问这是新手最常踩的坑。4.3 观察 stop_reason 分支第一课没有工具所以每次响应的stop_reason都是end_turn走的是打印文本分支。你可以在代码里临时加一行调试print_info(f[debug] stop_reason{response.stop_reason})跑一次对话你会看到每次都是end_turn。等第二课加入工具后当模型决定调工具时这里会变成tool_use循环就会走另一个分支。你现在看到的“只有一个分支在跑”正是理解 Agent 自主决策的起点——决策点已经在了只是还没接上工具。4.4 退出与中断验证输入quit或exit脚本打印“再见”并退出。按CtrlC同样能干净退出不会抛一堆 traceback。这个细节在常驻型 Agent 里很重要因为后面加心跳后Agent 会长时间运行退出路径必须可靠。5. 本篇常见错排查5.1 API Error: 401 或 authentication最常见的原因是.env没被正确加载。检查三点.env文件是否在load_dotenv指向的路径ANTHROPIC_API_KEY是否拼写正确key 前后有没有多余空格。load_dotenv的overrideTrue会让本地文件覆盖系统变量如果你系统里恰好有个旧的同名变量不加这个参数就会被旧值覆盖。5.2 第二句对话模型“失忆”几乎都是messages定义位置错了。它必须在while True外面定义循环内只做append。如果你在循环内写messages []每轮都清空模型自然记不住。对照第 3.2 节的代码确认messages: list[dict] []在agent_loop()函数体开头、while之前。5.3 stop_reason 是 tool_use 但没工具第一课如果模型返回tool_use说明你的系统提示词或模型行为触发了工具意图但本节没注册工具。代码里已经做了兜底打印提示并继续。这不是 bug是设计。等 s02 加入 dispatch table 后这个分支才会真正执行工具。5.4 循环停不下来如果你自己改了代码把退出条件删了或者max_turns没生效循环会一直跑。第一课的退出靠quit/exit关键字和CtrlC。如果你在 settings.json 里配了max_turns记得在循环里加计数器并在超限时 break否则那个字段只是摆设。5.5 中文输出乱码终端编码问题。Linux/macOS 一般没事Windows 下如果乱码在脚本开头加import sys sys.stdout.reconfigure(encodingutf-8)或者把终端切到 UTF-8 编码。这跟 Agent 逻辑无关但会干扰你观察输出。6. 下一步从循环到工具调用第一课你跑通的这个闭环是整个 claw0 网关的地基。while True负责“一直醒着”stop_reason负责“该干什么”messages[]负责“记得住”。后面九节课工具调用、会话持久化、Telegram 和飞书通道、五级绑定路由、心跳与定时任务、可靠投递、三层重试、并发车道全是在这个骨架上挂模块循环本身一行不改。如果你想把模型接入层也配得更顺手可以去 TaoToken 的模型对话页面直接试不同模型在同样提示词下的表现对比哪个更适合你的 Agent 场景长期跑编码类 Agent 的话Coding Plan 的额度模型更划算。接入文档里有完整的 base_url 和参数说明排障时对着看比猜快得多。现在你手上有一个能跑、能记上下文、能干净退出的 Agent 循环。下一课我们让它学会伸手拿工具。