1. 为什么你的第一个 Agent 总是跑不通很多人第一次做自定义 Agent卡住的地方往往不是模型能力而是三件小事Key 散落在各个脚本里、YAML 配置写完不知道对不对、Python 入口跑起来没有任何反馈。我见过太多项目Prompt 写得挺漂亮结果一运行就报 401或者工具注册了但模型根本不调用。这篇就解决这个问题用 OpenClaw 定义一个自定义 Agent角色和 Prompt 写在 YAML 里执行入口用 Python 写模型通道统一走 TaoToken 的 Key。你不需要在多个平台之间来回切换也不需要把 Key 硬编码到每个文件里。适合刚接触 Agent 开发、想先跑通一条完整链路的人也适合手里已经有一堆脚本、想统一模型入口的开发者。整篇的节奏是先给最小可运行骨架再补配置细节然后验证请求最后把常见报错逐个拆掉。你跟着敲一遍应该能在半小时内看到 Agent 正常返回结果。2. TaoToken 前置把 Key 和通道先准备好TaoToken 在这里扮演的角色是统一的模型接入层。你不需要为每个模型单独申请 Key也不需要改代码里的 base_url。一个 Key 走通对话、编码、Agent 调用这些场景对自定义 Agent 来说最直接的好处就是YAML 里只写一个 provider 配置Python 里只读一个环境变量。先到控制台创建一个 API Key。地址是 https://taotoken.net/api-keys 登录后新建 Key复制出来先放到一边。注意不要直接写进代码后面我们用环境变量注入。如果你还没决定用哪个模型可以先在模型对话页面试一下效果地址是 https://taotoken.net/models 选一个响应速度和成本都合适的。Agent 场景我一般建议先用中等规模的模型跑通流程确认工具调用正常后再换更强的。接入文档在 https://taotoken.net/doc 里面有 base_url 和请求格式的说明。TaoToken 的 API 入口是 https://taotoken.net/api 这个地址在 YAML 和 Python 里都会用到。注意 API 地址不带查询参数直接写就行。环境变量这样设置Linux 或 macOS 下export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设置完可以验证一下echo $TAOTOKEN_API_KEY能打印出 Key 就说明环境变量生效了。这一步看起来简单但后面 90% 的 401 报错都是因为这里没配对。3. 可复制配置agent.yaml 与 config.toml 骨架OpenClaw 的配置分两层agent.yaml 定义 Agent 的角色、Prompt 和工具config.toml 定义模型通道和运行参数。分开写的好处是换模型不用动 Agent 逻辑改 Prompt 不用碰通道配置。先看 agent.yaml。这是一个最小但完整的骨架你可以直接复制name: first-custom-agent version: 0.1.0 description: 一个用于演示的问答 Agent支持时间查询和文本统计 model: provider: taotoken model: gpt-4o-mini temperature: 0.3 max_tokens: 1024 memory: type: sliding_window window_size: 6 tools: - name: get_current_time description: 返回当前服务器时间格式为 YYYY-MM-DD HH:MM:SS enabled: true - name: count_text description: 统计输入文本的字符数。输入参数text字符串要统计的文本 enabled: true system_prompt: | 你是一个简洁的助手名字叫小爪。 规则 1. 用户问时间时必须先调用 get_current_time 工具不要自己编造时间。 2. 用户要求统计字数时必须调用 count_text 工具。 3. 如果不知道答案直接说不知道不要虚构。 4. 回答控制在三句话以内。 examples: - user: 现在几点了 assistant: - tool_call: get_current_time() - tool_result: 2025-03-15 10:30:00 - final: 现在是 2025-03-15 10:30:00。 - user: 帮我数一下你好世界有几个字 assistant: - tool_call: count_text(text你好世界) - tool_result: 4 - final: 你好世界共有 4 个字符。几个关键点。model.provider 写 taotoken表示走统一通道。temperature 设 0.3Agent 场景不需要太发散。tools 里每个工具都要有 name 和 descriptiondescription 写得越清楚模型越不容易乱调。system_prompt 里明确写了“必须先调用工具”这是防止模型自己编时间的关键。examples 给了两个少样本示例覆盖了工具调用和最终回答的格式。再看 config.toml它负责通道和运行参数[api] provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout 30 max_retries 2 [agent] config_path ./agent.yaml log_level DEBUG max_rounds 10 [tools] default_timeout 10base_url 写 TaoToken 的 API 地址api_key_env 指向刚才设置的环境变量名。log_level 先开 DEBUG方便看模型到底有没有调用工具。max_rounds 限制一轮会话最多 10 次交互防止死循环。目录结构建议这样放first_agent/ ├── agent.yaml ├── config.toml ├── tools.py ├── main.py └── requirements.txtrequirements.txt 内容openclaw-sdk1.0.0 requests2.31.0注意 openclaw-sdk 是演示用的包名实际使用时替换成你本地框架的包名导入路径按框架文档调整。4. Python 入口与工具实现工具写在 tools.py 里。OpenClaw 用装饰器把普通函数注册成工具模型通过 description 决定什么时候调用。import datetime from openclaw import tool, ToolException tool( nameget_current_time, description返回当前服务器时间格式为 YYYY-MM-DD HH:MM:SS ) def get_current_time() - str: now datetime.datetime.now() return now.strftime(%Y-%m-%d %H:%M:%S) tool( namecount_text, description统计输入文本的字符数。输入参数text字符串要统计的文本, parameters{ text: { type: string, description: 需要统计字符数的文本内容 } } ) def count_text(text: str) - str: if not isinstance(text, str): raise ToolException(text 必须是字符串) return str(len(text))get_current_time 没有参数模型调用时不需要传值。count_text 有一个 text 参数parameters 里写清楚类型和描述模型生成的调用参数会更准确。ToolException 是框架内置异常抛出后框架会按 config.toml 里的 max_retries 重试。然后是 main.py负责加载配置、注册工具、启动对话import os from openclaw import Agent from tools import get_current_time, count_text def build_agent(): api_key os.environ.get(TAOTOKEN_API_KEY) if not api_key: raise RuntimeError(未找到 TAOTOKEN_API_KEY请先设置环境变量) agent Agent.from_config(config.toml) agent.register_tool(get_current_time) agent.register_tool(count_text) return agent def main(): agent build_agent() print(Agent 已启动输入 exit 退出。) while True: user_input input(你: ).strip() if user_input.lower() in (exit, quit): print(再见。) break if not user_input: continue try: result agent.run_sync(user_input) print(f小爪: {result[text]}) except Exception as e: print(f运行出错: {e}) if __name__ __main__: main()这里的关键是 Agent.from_config(config.toml)它会读取通道配置和 agent.yaml 路径。register_tool 把两个工具注册进去。run_sync 是同步调用返回结果里取 text 字段就是最终回答。如果你想把 Agent 跑成一次性调用而不是交互式可以改成result agent.run_sync(现在几点了) print(result[text])5. 验证请求从启动到成功返回先确认环境变量还在echo $TAOTOKEN_API_KEY然后运行python main.py正常启动后你会看到Agent 已启动输入 exit 退出。 你:输入第一个测试问题你: 现在几点了因为开了 DEBUG 日志你会看到类似这样的输出DEBUG - LLM 决定调用工具: get_current_time DEBUG - 工具返回: 2025-03-15 10:30:00 小爪: 现在是 2025-03-15 10:30:00。再测第二个工具你: 帮我数一下你好世界有几个字预期输出DEBUG - LLM 决定调用工具: count_text DEBUG - 工具返回: 4 小爪: 你好世界共有 4 个字符。再测一个不需要工具的你: 你好预期输出小爪: 你好有什么可以帮你如果这三条都通过了说明 YAML 配置、Python 入口、TaoToken 通道、工具注册这条链路已经完整跑通。你可以打开 https://taotoken.net/console 看一下调用记录确认请求确实走了 TaoToken 通道。6. 本篇常见错排查6.1 报 401 Unauthorized最常见的原因是环境变量没生效。先确认echo $TAOTOKEN_API_KEY如果为空重新 export 一次。如果是在 IDE 里运行注意 IDE 可能没有继承终端的环境变量需要在运行配置里手动加。还有一种情况是 Key 复制时带了空格重新复制一遍。6.2 模型不调用工具直接自己回答看 DEBUG 日志如果模型没有输出 tool_call说明 system_prompt 里的约束不够强。把“必须先调用 get_current_time 工具”放到 Prompt 最前面并且在 examples 里保留工具调用示例。另外检查 tools 里的 description 是否写得太模糊模型看不懂就不会调。6.3 YAML 解析失败报错通常是yaml.scanner.ScannerError。检查缩进是否用了 TabYAML 只认空格。检查 system_prompt 里的中文引号如果 Prompt 里有冒号或特殊字符用|块标量包起来。examples 里的 tool_result 如果是字符串记得加引号。6.4 工具注册了但报 not found检查 tools.py 里的 name 和 agent.yaml 里的 tools.name 是否完全一致大小写也要对。检查 main.py 里 register_tool 是否真的调用了。如果框架要求工具在 Agent 初始化前注册调整一下顺序。6.5 请求超时config.toml 里 timeout 设 30 秒如果网络慢可以调到 60。max_retries 设 2不要设太大否则一个失败请求会卡很久。工具内部的 default_timeout 设 10 秒避免某个工具卡住整个流程。6.6 模型返回英文在 system_prompt 里明确写“只使用中文回答”examples 也全部用中文。如果还不行检查 model 配置里有没有 language 参数没有的话就在 Prompt 里多强调一次。7. 下一步把 Agent 用起来跑通之后你可以做几件事。第一把 config.toml 里的 log_level 改成 INFO减少日志噪音。第二把 agent.yaml 里的 model 换成更强的模型对比工具调用准确率。第三把 main.py 改成 FastAPI 接口让 Agent 可以被其他服务调用。第四如果你要做长期编码或 Agent 任务可以看一下 Coding Plan地址是 https://taotoken.net/coding-plan 里面有适合持续调用的方案。接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 模型对话测试在 https://taotoken.net/models 。这几个页面建议都收藏一下后面调模型和查报错会用得上。最后提醒一句YAML 里的 Prompt 和 examples 是 Agent 行为的地基不要一次写太复杂。先把一个工具调通再加第二个每加一个就测一次。这样出问题的时候你永远知道是哪一步引入的。