1. 先搞清楚 OpenClaw 到底在干什么从对话到能动手的 AgentOpenClaw 这个项目圈子里叫它“小龙虾”本质上是一个本地跑的 Agent 框架。它能做什么简单说就是让大模型不只是聊天还能调用工具、执行命令、读写文件、访问 HTTP 接口。适合谁适合想在自己电脑上快速跑通一个 Agent、又不想被各种云平台绑定的人。我见过太多人把 OpenClaw 当成“装完就万能”的东西结果装完发现它什么都不会。原因很简单Agent 的能力边界取决于你给它配了什么工具和技能。OpenClaw 本身只是一个调度器它负责把用户输入、模型输出、工具执行结果串起来。真正干活的是模型和工具。所以这篇教程的目标很明确从零搭一个最小可用的 OpenClaw Agent让它能通过 HTTP 服务器接收请求调用大模型 API返回结果。整条链路里最关键的一环是 API Key 和 Base URL 的配置。我会用 TaoToken 的统一 Key 来打通模型调用这样你不需要在多个平台之间来回切换。先看整体架构。OpenClaw 的核心流程是这样的用户请求 → HTTP 服务器 → OpenClaw Agent → 模型 APITaoToken→ 工具执行 → 返回结果这里面有几个关键文件你需要知道SKILL.md技能描述文件告诉 Agent 它能做什么、怎么做config.toml或settings.jsonOpenClaw 的主配置文件里面填 Base URL、API Key、Model IDagent.py或入口脚本启动 Agent 和 HTTP 服务器的代码很多人卡在第一步模型 API 怎么接。OpenClaw 默认走 OpenAI 兼容协议所以只要你的 API 端点兼容/v1/chat/completions或/v1/responses就能直接接。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 协议填进去就能用。我试过用其他平台的 Key每个平台都要单独配环境变量、单独改 Base URL切换模型的时候特别麻烦。TaoToken 的好处是一个 Key 可以调多个模型Base URL 统一Model ID 按需换。对于 OpenClaw 这种需要频繁切换模型的场景省事很多。接下来我会一步步带你走完先拿到 TaoToken 的 Key然后写 SKILL.md再配 OpenClaw 的 settings最后用 curl 验证整条链路通不通。每一步都有可复制的代码和配置你跟着做就行。2. TaoToken 前置准备统一 Key 与 Base URL 填写位置在开始写 OpenClaw 配置之前你需要先拿到 TaoToken 的 API Key。这一步很快但有几个细节要注意不然待会儿配置的时候会卡住。首先访问 TaoToken 官网注册账号https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册完成后进入控制台找到 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。在这里创建一个新的 Key复制出来保存好。这个 Key 就是你后面填到 OpenClaw 配置里的凭证。注意Key 只显示一次复制后存到安全的地方。如果你用环境变量管理可以写成TAOTOKEN_API_KEY后面配置文件里引用这个变量就行。TaoToken 的 API 端点有两个你需要记住Base URLhttps://taotoken.net/api兼容协议OpenAI Chat Completions / ResponsesOpenClaw 的配置文件里Base URL 填https://taotoken.net/api不要加/v1OpenClaw 会自动拼接路径。如果你填成https://taotoken.net/api/v1可能会遇到 404 或者路径重复的问题。这个坑我踩过当时排查了半天才发现是 Base URL 多写了一层。Model ID 怎么填TaoToken 支持多个模型你可以在模型对话页面查看可用列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。常见的比如gpt-4o、claude-3-5-sonnet、deepseek-chat等。OpenClaw 配置里填你实际要用的 Model ID后面切换模型只需要改这一个字段。如果你打算长期跑 Agent 任务建议看一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要频繁调用模型、跑自动化任务的场景比按量计费更划算。现在你手里应该有这些东西项目值API Key从控制台复制的那串字符Base URLhttps://taotoken.net/apiModel ID比如gpt-4o或claude-3-5-sonnet配置文件路径OpenClaw 项目根目录下的settings.toml或config.json把这些准备好接下来写 SKILL.md 和 OpenClaw 配置就顺了。3. 可复制配置SKILL.md 模板与 OpenClaw settings 片段这一节是整篇教程的核心。我会给你两份可直接复制的配置一份是SKILL.md一份是 OpenClaw 的settings.toml。你只需要把里面的 API Key 和 Model ID 换成自己的就能跑起来。先看SKILL.md。这个文件的作用是告诉 Agent 它能做什么、怎么做。OpenClaw 启动时会读取这个文件把里面的内容作为系统提示的一部分传给模型。所以 SKILL.md 写得越清楚Agent 的行为越可控。下面是一个最小可用的 SKILL.md 模板包含两个技能执行本地命令和调用 HTTP 接口。# SKILL.md ## 技能执行本地命令 当用户要求执行系统命令、创建文件、查看目录时使用以下格式回复 命令要执行的命令 规则 1. 只输出一行以“命令”开头后面跟命令本体 2. 不要输出解释、Markdown 代码块或多余文字 3. 命令执行结果会回传给你根据结果决定下一步 ## 技能调用 HTTP 接口 当用户要求获取天气、查询 API 数据时使用以下格式 命令curl -s https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY 规则 1. 所有 HTTP 请求通过 curl 执行 2. 需要认证的接口从环境变量读取 Key 3. 返回结果会回传给你解析后回复用户 ## 技能对话与推理 当不需要执行命令时直接用自然语言回复用户。 不要以“命令”开头。这个模板的关键点是明确告诉模型“什么时候输出命令、什么时候输出自然语言”。OpenClaw 的调度器会根据回复内容判断是否要执行命令。如果模型输出以“命令”开头调度器就提取命令并执行否则直接把回复返回给用户。接下来是 OpenClaw 的settings.toml。这个文件通常放在项目根目录OpenClaw 启动时会自动读取。[model] provider openai base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id gpt-4o max_tokens 4096 temperature 0.7 [agent] name openclaw-agent skill_file SKILL.md max_iterations 10 [server] host 0.0.0.0 port 8080如果你用的是 JSON 格式的配置等价写法如下{ model: { provider: openai, base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model_id: gpt-4o, max_tokens: 4096, temperature: 0.7 }, agent: { name: openclaw-agent, skill_file: SKILL.md, max_iterations: 10 }, server: { host: 0.0.0.0, port: 8080 } }几个参数说明base_url填https://taotoken.net/api不要加/v1api_key你的 TaoToken Key建议用环境变量替换model_id按需填比如gpt-4o、claude-3-5-sonnetmax_iterationsAgent 最多执行多少轮工具调用防止死循环portHTTP 服务器监听端口手机访问时用这个端口如果你用环境变量管理 Key可以把api_key改成api_key_env TAOTOKEN_API_KEY然后在启动脚本里 export 这个变量。这样配置文件可以提交到 Git不会泄露 Key。配置写完后启动 OpenClawexport TAOTOKEN_API_KEYsk-你的TaoTokenKey python -m openclaw --config settings.toml如果启动成功你会看到类似这样的输出[INFO] OpenClaw agent started [INFO] Model: gpt-4o https://taotoken.net/api [INFO] HTTP server listening on 0.0.0.0:8080 [INFO] Skill file loaded: SKILL.md到这里配置部分就完成了。下一节我会用 curl 验证整条链路确保 Agent 能正常调用模型 API。4. 验证请求用 curl 测试 Agent 调用 API 是否成功配置写好了但你怎么知道它真的通了最直接的办法是用 curl 发一个请求看返回结果。这一节我会给你完整的 curl 命令和预期返回你照着做就能确认整条链路是否正常。先验证模型 API 本身是否可用。这一步绕过 OpenClaw直接调 TaoToken 的接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o, messages: [ {role: user, content: 回复一个字通} ], max_tokens: 10 }预期返回{ id: chatcmpl-xxx, object: chat.completion, created: 1700000000, model: gpt-4o, choices: [ { index: 0, message: { role: assistant, content: 通 }, finish_reason: stop } ], usage: { prompt_tokens: 10, completion_tokens: 1, total_tokens: 11 } }如果你看到choices[0].message.content有内容说明模型 API 通了。如果返回 401检查 Key 是否正确如果返回 404检查 Base URL 是否多写了/v1。接下来验证 OpenClaw 的 HTTP 服务器。假设你已经启动了 OpenClaw监听在8080端口。发一个请求curl -s http://localhost:8080/chat \ -H Content-Type: application/json \ -d { message: 帮我在当前目录创建一个 hello.txt内容是 OpenClaw 测试 }预期返回{ reply: 已创建 hello.txt内容为OpenClaw 测试, tool_calls: [ { command: echo OpenClaw 测试 hello.txt, exit_code: 0, output: } ] }然后检查文件是否真的创建了cat hello.txt预期输出OpenClaw 测试如果这一步成功说明整条链路通了HTTP 请求 → OpenClaw Agent → 模型 API → 工具执行 → 返回结果。再验证一个 HTTP 调用技能。发一个天气查询请求curl -s http://localhost:8080/chat \ -H Content-Type: application/json \ -d { message: 帮我查一下北京的天气 }预期返回里会包含tool_calls里面有一条 curl 命令执行结果会回传给模型模型再整理成自然语言回复。如果你在手机上也配好了访问地址可以用手机浏览器打开http://你的电脑IP:8080发一条消息试试。能收到回复就说明远程链路也通了。到这里验证部分就完成了。下一节我会列出几个常见的报错和排查方法帮你快速定位问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易遇到这几类报错。我按出现频率从高到低排列每个都给出具体现象和解决方法。401 Unauthorized现象curl 返回{error: {message: Invalid API key, type: invalid_request_error}}。原因API Key 填错了或者环境变量没生效。排查步骤检查settings.toml里的api_key是否和 TaoToken 控制台里的一致如果用环境变量确认echo $TAOTOKEN_API_KEY有输出检查 Key 是否被删除或过期去控制台重新生成一个# 确认环境变量 echo $TAOTOKEN_API_KEY # 重新测试 curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEYlocal proxy failed现象OpenClaw 启动时报local proxy failed: connection refused或proxy error。原因Base URL 填错了或者网络不通。排查步骤确认base_url是https://taotoken.net/api不要加/v1用 curl 直接测 Base URL 是否可达检查是否有本地代理配置干扰临时取消HTTP_PROXY和HTTPS_PROXY环境变量# 测试连通性 curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY # 取消代理 unset HTTP_PROXY unset HTTPS_PROXYreading choices 报错现象TypeError: Cannot read properties of undefined (reading choices)或类似。原因API 返回格式和预期不一致通常是 Base URL 路径拼接错误或者 Model ID 不存在。排查步骤确认 Base URL 没有多余路径确认 Model ID 在 TaoToken 支持列表里用 curl 直接调一次看返回结构curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d {model: gpt-4o, messages: [{role: user, content: hi}]}如果返回里没有choices字段说明请求本身有问题检查 Model ID 和请求体格式。OAuth 相关报错现象OAuth token expired或invalid_grant。原因如果你用的是 Claude Code 或 Codex 的 OAuth 认证方式Token 过期了。排查步骤重新走一遍 OAuth 授权流程如果用的是 TaoToken 的 Key确认没有混用 OAuth 配置检查auth.json或credentials.json里的 Token 是否过期如果你在 OpenClaw 里同时配了 OAuth 和 API Key可能会冲突。建议只用一种认证方式TaoToken 的 Key 方式最简单直接填api_key就行。CC Switch / Cline MCP / Codex auth.json 三件套如果你在用 CC Switch 或 Cline 的 MCP 功能配置里必须写全三件套{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model_id: gpt-4o }缺任何一个都会报错。Codex 的auth.json里也是同样三个字段路径通常在~/.codex/auth.json。排查完这些基本能覆盖 90% 的常见问题。如果还有报错去接入文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 接入文档与 API Keys 入口把 OpenClaw 跑成长期可用的 Agent配置跑通之后你可能会想把它变成一个长期可用的服务。比如让 OpenClaw 常驻后台手机随时能访问或者接入更多技能。这一节给你几个实用建议和入口。首先把 OpenClaw 做成 systemd 服务开机自启[Unit] DescriptionOpenClaw Agent Afternetwork.target [Service] Typesimple Useryouruser WorkingDirectory/home/youruser/openclaw EnvironmentTAOTOKEN_API_KEYsk-你的TaoTokenKey ExecStart/usr/bin/python3 -m openclaw --config settings.toml Restartalways RestartSec10 [Install] WantedBymulti-user.target保存到/etc/systemd/system/openclaw.service然后sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw这样 OpenClaw 就会在后台常驻崩溃了自动重启。其次扩展 SKILL.md。你可以往里面加更多技能比如发送邮件、读写数据库、调用第三方 API。每加一个技能Agent 的能力就多一分。但注意不要一次加太多容易让模型混淆。建议按需添加测试通过后再加下一个。如果你需要更稳定的模型调用配额可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合长期跑 Agent 任务的场景比按量计费更可控。API Key 管理入口在这里https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。建议定期轮换 Key避免泄露。接入文档里有更详细的参数说明和示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。遇到问题先查文档大部分报错都有对应说明。最后如果你只是想快速验证模型效果可以直接在模型对话页面测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。不用写代码选模型、输问题、看回复确认模型可用后再接到 OpenClaw 里。整条链路跑通后你会发现 OpenClaw 的核心并不复杂一个 HTTP 服务器接收请求一个调度器管理模型调用和工具执行一个 SKILL.md 定义能力边界。真正决定 Agent 好不好用的是你给它配了什么技能、写了什么提示词。多试几次调整 SKILL.md 里的规则你会慢慢找到适合自己场景的配置。