1. 为什么第 1 周最容易卡在模型接入
刚把 OpenClaw 的环境装好，npm install跑完，onboarding 向导也走了一遍，结果第一次让 Agent 说话就报错——这几乎是每个 OpenClaw 新手都会遇到的场景。问题往往不在 OpenClaw 本身，而在模型接入这一环：Key 放错位置、base_url 少写一段、协议类型选错、环境变量没生效，任何一个细节都能让 Agent 卡在“思考中”然后超时。
OpenClaw 是一个开源的自主 AI Agent 开发框架，核心链路是 Gateway → LLM → Tools & Skills。其中 LLM 层就是 Agent 的大脑，负责推理、拆解任务、决定调用哪个工具。如果这一层连不通，后面 Skills、ClawHub、Heartbeats 全都无从谈起。所以 5 周学习路线的第 1 周，目标非常明确：让 OpenClaw 稳定连通一个可用的模型服务，跑通一次完整的 Agent 对话请求。
这篇聚焦的就是这个环节。我会给出两套可直接复制的配置骨架——settings.json和config.toml，分别对应 OpenClaw 在不同初始化方式下的配置文件形态，并用 TaoToken 作为统一的模型接入通道。TaoToken 提供 OpenAI 兼容的 API 接口，一个 Key 就能调用多种主流模型，省去在多个平台之间来回切换 Key 的麻烦。对于刚搭好环境、准备跑通首个自主 Agent 的开发者来说，这是最快能验证链路的方式。
适合谁看：已经完成 OpenClaw 基础安装、Node.js 和 Python 依赖就绪、准备配置 LLM 层的开发者。如果你还没装环境，建议先回到 Phase 2 的环境搭建步骤，把 WSL2 或原生环境准备好再往下走。
2. TaoToken 前置准备：拿到统一 Key 和 API 地址
在改配置文件之前，先把两样东西准备好：API Key 和 base_url。TaoToken 的接入地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base_url 使用。Key 的获取在控制台的 API Keys 页面完成，登录后新建一个 Key，复制出来先存到临时文本里，后面配置要用。
这里有个容易踩的坑：很多人会把官网地址https://taotoken.net直接填进 base_url，结果请求打到首页而不是 API 端点，返回一堆 HTML 而不是 JSON。记住，base_url 必须是https://taotoken.net/api，OpenClaw 或 OpenAI SDK 会自动在这个地址后面拼接/v1/chat/completions这类路径。
如果你用的是 OpenAI 兼容协议，模型名称直接填你想要的模型 ID 即可。TaoToken 的模型列表在文档里有完整说明，常见的有 claude 系列、gpt 系列、deepseek 系列等。第一次验证建议选一个响应快的轻量模型，先把链路跑通，再换成你实际要用的模型。
注意：Key 不要硬编码在会提交到 Git 的文件里。下面两套配置我都会用环境变量引用的方式，既安全又方便切换。
准备好 Key 之后，可以先在终端里用 curl 快速验证一下这个 Key 能不能通，避免改完配置文件才发现是 Key 本身的问题：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -d '{ "model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16 }'如果返回的是包含choices字段的 JSON，说明 Key 和地址都没问题，可以进入下一步配置 OpenClaw。如果返回 401，检查 Key 是否复制完整；返回 404，检查 base_url 是否写成了官网首页。
3. 可复制配置：settings.json 与 config.toml 双版本
OpenClaw 的配置入口取决于你的初始化方式。通过 onboarding 向导生成的通常是settings.json，放在项目根目录或~/.openclaw/下；如果你用的是手动初始化的 TOML 配置，则是config.toml。两套配置的字段名略有差异，但核心逻辑一致：指定 provider 类型、base_url、api_key 和默认模型。
3.1 settings.json 版本
这是最常见的一种形态，适合通过 npm 安装后由向导生成的配置。打开settings.json，找到llm或models节点，按下面的结构填写：
{ "llm": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "defaultModel": "claude-3-5-sonnet", "timeout": 60000, "maxRetries": 2 }, "agent": { "name": "my-first-agent", "soulFile": "./SOUL.md", "sandbox": true } }几个关键点说明。provider填openai-compatible，因为 TaoToken 走的是 OpenAI 兼容协议，这样 OpenClaw 会用标准的/v1/chat/completions路径发请求。baseUrl就是前面强调的https://taotoken.net/api，不要加/v1，框架会自己拼。apiKey用${TAOTOKEN_API_KEY}引用环境变量，这样配置文件可以安全地提交到仓库。timeout设 60 秒，Agent 任务有时推理链较长，太短容易误判超时。maxRetries设 2，网络抖动时自动重试。
环境变量的设置方式，在 WSL 或 Linux 下：
export TAOTOKEN_API_KEY="你的Key"想持久化就写进~/.bashrc或~/.zshrc。Windows 原生环境用setx TAOTOKEN_API_KEY "你的Key"，然后重开终端。
3.2 config.toml 版本
如果你用的是 TOML 配置，结构如下：
[llm] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" default_model = "claude-3-5-sonnet" timeout = 60000 max_retries = 2 [agent] name = "my-first-agent" soul_file = "./SOUL.md" sandbox = true注意 TOML 里字段名是下划线风格base_url、api_key，和 JSON 的驼峰不同，这是两种格式的惯例差异，别混用。其余含义完全一致。
3.3 参数对照表
| 参数（JSON） | 参数（TOML） | 建议值 | 作用 |
|---|---|---|---|
| provider | provider | openai-compatible | 协议类型，TaoToken 走 OpenAI 兼容 |
| baseUrl | base_url | https://taotoken.net/api | API 端点，不带 /v1 |
| apiKey | api_key | ${TAOTOKEN_API_KEY} | 环境变量引用，避免硬编码 |
| defaultModel | default_model | claude-3-5-sonnet | 默认调用的模型 ID |
| timeout | timeout | 60000 | 单次请求超时毫秒数 |
| maxRetries | max_retries | 2 | 失败自动重试次数 |
改完配置后，重启 OpenClaw 服务让配置生效。如果是通过npm run dev启动的，Ctrl+C 停掉再重新跑一次即可。
4. 验证请求：跑通第一次 Agent 对话
配置改完不代表链路通了，必须发一次真实请求验证。OpenClaw 启动后，本地控制 UI 通常在http://localhost:3000或终端里会打印实际端口。打开 UI，找到对话入口，发一句最简单的指令，比如“你好，帮我列出当前目录下的文件”。
如果 Agent 正常回复，并且日志里能看到对 Tools 层的调用记录，说明 LLM 层已经连通。更直接的验证方式是看终端日志，成功的请求会打印类似这样的记录：
[LLM] POST https://taotoken.net/api/v1/chat/completions [LLM] model=claude-3-5-sonnet status=200 latency=1240ms [Agent] tool_call: list_files(path=".") [Agent] response generated, tokens_in=86 tokens_out=142看到status=200和tool_call这两行，基本可以确认模型接入成功。如果只想验证模型本身而不触发工具调用，可以在 UI 里发一句纯对话，比如“用一句话解释什么是串行队列”，观察是否正常返回文本。
还有一种命令行验证方式，适合不想开 UI 的场景。OpenClaw 一般提供 CLI 入口：
openclaw chat --message "ping" --model claude-3-5-sonnet返回内容里如果包含模型生成的文本，说明配置读取正确。这一步能过，第 1 周的核心目标就达成了。
5. 本篇常见报错排查清单
配置过程中最容易遇到的几类报错，我按出现频率排一下，对照着查基本能覆盖九成问题。
401 Unauthorized：Key 无效或没读到。先确认环境变量在当前 shell 里echo $TAOTOKEN_API_KEY有输出。如果配置文件里直接写了 Key 而不是引用变量，检查有没有多余空格或换行。Key 本身失效的话，去控制台重新生成一个。
404 Not Found：base_url 写错。最常见的是写成了https://taotoken.net或https://taotoken.net/api/v1。正确值是https://taotoken.net/api，框架自己拼/v1/chat/completions。多写或少写/v1都会 404。
Connection timeout：网络不通或 timeout 太短。先确认能访问https://taotoken.net/api，再检查timeout是否设得太小。Agent 任务推理链长时，建议不低于 60000 毫秒。
model not found：模型 ID 拼错。模型名称区分大小写，去文档里复制准确的 ID，不要凭记忆手写。
配置不生效：改了文件但行为没变。检查是不是改错了配置文件位置，OpenClaw 可能同时存在项目级和用户级配置，优先级不同。重启服务，确认加载的是你改的那份。
环境变量读不到：在 WSL 里设了变量，但 OpenClaw 跑在 Windows 侧，或者反过来。确认变量设在 OpenClaw 实际运行的那个环境里，设完重开终端。
提示：排查时优先看终端日志里的完整请求 URL 和状态码，比在 UI 上猜要快得多。日志里会打印实际请求的地址，一眼就能看出 base_url 拼对没有。
6. 下一步：从跑通到稳定，以及后续路线
第 1 周把模型接入跑通之后，不要急着上复杂技能。先让 Agent 稳定运行几天，观察日志里有没有偶发的超时或重试，确认maxRetries和timeout的组合在你的网络环境下够用。稳定连通是后面所有阶段的地基，这一步偷懒，后面调 Skills 和 Heartbeats 时会反复回来补课。
如果你打算长期做编码类 Agent 或者多智能体编排，可以了解一下 Coding Plan，它在调用额度和模型路由上有更适合持续开发的配置。日常验证模型响应、快速试不同模型的效果，用模型对话入口就够了。需要管理多个 Key 或查看调用量，去控制台。接入文档里有完整的参数说明和更多模型列表，配置遇到不确定的字段先查文档再改。
跑通第一次对话只是起点。接下来按 5 周路线走，Phase 3 开始对接邮箱和日历，Phase 4 进入自定义技能开发，那时候你会庆幸第 1 周把模型接入这层打扎实了。
