1. 从零装好 OpenClaw 却卡在模型通道：我踩过的三个坑
OpenClaw（原 Clawdbot）是一个轻量级的 AI 任务自动化框架，你可以把它理解成一个「本地跑得动、能挂 Skills、能接各种模型通道」的 Agent 运行时。它能做什么？简单说就是：你给它一个任务描述，它自己拆步骤、调工具、跑 Skills，最后把结果吐回来。适合谁？适合想在自己机器或小服务器上跑自动化流程、又不想被某一家模型厂商绑死的开发者。
我这次的目标很明确：装好 OpenClaw，把 Skills 目录跑通，然后把settings里的模型通道从默认配置改到 TaoToken 的统一 Key/API 通道，最后验证一次真实调用能返回正常结果。
前两次尝试都翻车了。第一次是 Skills 列表死活加载不出来，日志里只有一行skills directory not found；第二次是模型通道改完，请求直接报local proxy failed，我一度以为是网络问题，折腾半天才发现是settings里 base URL 和 model id 没对齐。第三次我把整个链路拆成「安装 → 配置 → 验证」三段，逐段确认，才跑通。
这篇就按这个顺序写，重点放在settings配置片段和 Skills 目录结构上，每一步都给可复制的命令和配置。你跟着做，基本能避开我踩的那几个坑。
先说清楚整体链路：OpenClaw 本体负责调度，Skills 是它调用的能力单元（放在固定目录里，按约定格式声明），模型通道则由settings文件里的 provider 配置决定。三者关系是——OpenClaw 启动时读settings拿到模型通道，运行时按任务需要去 Skills 目录加载对应能力，再通过模型通道发起请求。所以任何一环配置错了，表现都是「启动没报错但调用失败」，这也是最容易让人误判的地方。
下面进入正题。我会先讲安装和目录准备，再讲 TaoToken 通道的前置准备，然后是核心的settings配置片段，接着是逐项验证动作，最后是常见报错排查。
2. 安装 OpenClaw 与 Skills 目录准备：settings 文件到底在哪
安装 OpenClaw 本身不复杂，关键是搞清楚它的目录结构，尤其是settings文件和 Skills 目录的位置。很多人装完找不到配置文件，就是因为不知道默认路径。
我用的方式是源码安装，这样目录结构最清晰，也方便后面改settings。先确认基础环境：Node.js 18 以上、npm 或 pnpm、git。我用的是 Node 20 + pnpm。
# 确认 Node 版本，低于 18 先升级 node -v # 确认包管理器 pnpm -v # 拉取 OpenClaw 源码（2026 稳定分支） git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖 pnpm install # 构建 pnpm build构建完成后，目录里会出现几个关键路径，我列一下，你对照自己的实际情况：
openclaw/ ├── settings.json # 主配置文件，模型通道在这里改 ├── skills/ # Skills 根目录 │ ├── example-skill/ │ │ ├── skill.json # Skill 声明文件 │ │ └── index.js # Skill 执行逻辑 │ └── ... ├── data/ # 运行时数据、日志 └── package.json如果你是用 npm 全局安装的，settings.json一般在用户目录下，比如~/.openclaw/settings.json，Skills 目录则是~/.openclaw/skills/。两种方式都行，我建议源码安装，路径可控，出问题好排查。
Skills 目录的结构有约定，不是随便放个 js 文件就能被识别。每个 Skill 是一个子目录，里面必须有skill.json，声明名称、版本、入口文件、参数 schema。举个最小可用的例子：
{ "name": "echo-skill", "version": "1.0.0", "description": "回显输入内容，用于验证 Skills 加载链路", "entry": "index.js", "parameters": { "type": "object", "properties": { "text": { "type": "string", "description": "要回显的文本" } }, "required": ["text"] } }对应的index.js：
module.exports = async function ({ text }) { return { echoed: text, timestamp: Date.now() }; };这个 echo-skill 后面验证环节会用到，先建好。注意skill.json里的entry必须和实际文件名一致，大小写敏感，这是 Skills 列表加载失败最常见的原因之一。
装完之后先别急着改模型通道，先跑一次启动，确认本体没问题：
# 启动 OpenClaw pnpm start # 正常输出类似： # [openclaw] server listening on :3000 # [openclaw] skills loaded: 1 # [openclaw] settings loaded from ./settings.json如果这里就报错，先解决启动问题，别往下走。启动无报错是后面所有验证的前提。我见过有人启动日志里其实有skills loaded: 0，但没注意，后面调用一直失败还以为是模型通道的问题。
到这里，安装和目录准备就完成了。下一步是准备 TaoToken 的通道信息，也就是 Key 和 API 地址。
3. 把 settings 改到 TaoToken 通道：可复制的配置片段
这一步是全文核心。OpenClaw 的模型通道由settings.json里的 provider 配置决定，默认可能指向某个内置通道，我们要把它改成 TaoToken 的统一 Key/API 通道。
先说前置准备。你需要一个 TaoToken 的 API Key。获取入口在控制台的 API Keys 页面，登录后创建即可。TaoToken 的 API 地址是https://taotoken.net/api，这个地址在配置里会用到。如果你还没注册，可以从官网入口进：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 Key。
拿到 Key 之后，打开settings.json。默认内容大概长这样（不同版本略有差异）：
{ "server": { "port": 3000 }, "skills": { "dir": "./skills" }, "model": { "provider": "default", "baseUrl": "https://some-default-endpoint/v1", "apiKey": "", "modelId": "default-model" } }我们要改的是model这一段。改成 TaoToken 通道后：
{ "server": { "port": 3000 }, "skills": { "dir": "./skills" }, "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "你的TaoToken API Key", "modelId": "claude-sonnet-4-20250514", "timeout": 60000, "maxRetries": 2 } }几个关键点必须对齐，错一个就会报错：
provider填openai-compatible，因为 TaoToken 的 API 是 OpenAI 兼容格式，OpenClaw 用这个 provider 类型去发请求。
baseUrl填https://taotoken.net/api，注意不要多加/v1，OpenClaw 内部会自己拼路径。我第二次翻车就是这里多写了/v1，结果请求打到https://taotoken.net/api/v1/chat/completions之外的路径，直接 404。
apiKey填你创建的那串 Key，注意不要带多余空格。
modelId填你要用的模型 ID，比如claude-sonnet-4-20250514。这个 ID 要和 TaoToken 支持的模型列表一致，填错了会报model not found。
如果你用的是 TOML 格式的配置（部分版本支持），等价写法是：
[server] port = 3000 [skills] dir = "./skills" [model] provider = "openai-compatible" baseUrl = "https://taotoken.net/api" apiKey = "你的TaoToken API Key" modelId = "claude-sonnet-4-20250514" timeout = 60000 maxRetries = 2改完保存，重启 OpenClaw：
pnpm start启动日志里应该能看到settings loaded和model provider: openai-compatible。如果日志里 provider 还是 default，说明你的settings.json路径不对，OpenClaw 读的是另一个文件。用pnpm start --verbose可以看到它实际加载的配置路径。
这里补一句：如果你同时用 Claude Code 或 Cline 这类工具，它们的配置逻辑类似，都是 Base URL + Key + Model ID 三件套。TaoToken 的接入文档里有各工具的配置示例，可以对照着看，入口在接入文档页。
配置改完只是第一步，能不能真正跑通，得靠验证。下一节讲逐项验证动作。
4. 逐项验证：启动无报错、Skills 可加载、示例调用返回正常
配置改完不能只看启动日志，要逐项验证。我按三个层次来：启动层、Skills 层、调用层。每一层都有明确的成功标志，任何一层不过，都别往下走。
第一层，启动无报错。重启后看日志：
pnpm start # 期望输出： # [openclaw] server listening on :3000 # [openclaw] settings loaded from ./settings.json # [openclaw] model provider: openai-compatible # [openclaw] skills loaded: 1四个关键行都要有。model provider必须是openai-compatible，skills loaded至少是 1（我们建了 echo-skill）。如果skills loaded: 0，去检查settings.json里skills.dir指向的目录，以及每个 Skill 子目录里有没有合法的skill.json。
第二层，Skills 列表可加载。OpenClaw 启动后有个 HTTP 接口可以查 Skills 列表：
curl http://localhost:3000/skills # 期望返回： # { # "skills": [ # { "name": "echo-skill", "version": "1.0.0", "description": "回显输入内容..." } # ] # }如果返回空数组，说明 Skills 没被扫描到。常见原因是skill.json格式错误，或者entry指向的文件不存在。用node -e "require('./skills/echo-skill/skill.json')"单独验证一下 JSON 是否合法。
第三层，示例调用返回正常。这是最关键的一步，它同时验证了模型通道和 Skills 执行链路。OpenClaw 提供一个调用接口：
curl -X POST http://localhost:3000/invoke \ -H "Content-Type: application/json" \ -d '{ "skill": "echo-skill", "parameters": { "text": "hello taotoken" } }' # 期望返回： # { # "success": true, # "result": { "echoed": "hello taotoken", "timestamp": 1730000000000 } # }注意，这个调用走的是 Skills 执行链路，不一定经过模型通道。要验证模型通道，得发一个需要模型推理的请求：
curl -X POST http://localhost:3000/chat \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "用一句话说明你正在通过哪个通道响应" } ] }' # 期望返回一段正常的模型回复文本如果这一步返回了正常文本，说明 TaoToken 通道打通了。如果报错，看下一节的排查。
我实测下来，这三层验证做完，基本能确认整条链路是通的。启动层确认配置被正确加载，Skills 层确认能力单元可被发现，调用层确认模型通道和 Skills 执行都正常。三层都过，才算真正装好。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节列几个我实际遇到过的报错，以及对应的排查方向。这些报错在 OpenClaw 接入 TaoToken 的过程中比较典型，你大概率会碰到其中一个。
报错一：401 Unauthorized
Error: request failed with status 401 {"error":{"message":"invalid api key","type":"authentication_error"}}这是 Key 的问题。排查顺序：先确认settings.json里apiKey没有多余空格或换行；再确认这个 Key 在 TaoToken 控制台是启用状态；最后确认 Key 没有过期。如果 Key 是从控制台复制的，注意别把前后引号也复制进去。我见过有人把 Key 用引号包起来填进 JSON，结果 Key 里带了引号字符，直接 401。
报错二：local proxy failed
Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890这个报错说明 OpenClaw 尝试走本地代理，但代理没开。如果你机器上配了全局代理环境变量（HTTP_PROXY/HTTPS_PROXY），OpenClaw 会继承。解决办法是在启动前清掉这些变量：
unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY pnpm start或者在settings.json里显式声明不走代理。这个报错和 TaoToken 本身无关，是本地网络环境的问题。
报错三：reading 'choices'
TypeError: Cannot read properties of undefined (reading 'choices')这个报错说明请求发出去了，但返回的 JSON 结构里没有choices字段。常见原因有两个：一是baseUrl配错了，请求打到了非 OpenAI 兼容的端点，返回了错误结构；二是modelId填错了，服务端返回了错误信息而不是正常的 completion 结构。排查方法：用 curl 直接打一次 TaoToken 的接口，看返回结构：
curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer 你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{ "role": "user", "content": "hi" }] }'如果这个 curl 返回正常，说明 Key 和模型 ID 没问题，那就是 OpenClaw 的baseUrl配置问题。重点检查有没有多写/v1。
报错四：OAuth 相关错误
Error: OAuth token exchange failed如果你在 OpenClaw 里配了 OAuth 类型的 provider，但实际用的是 API Key 通道，就会报这个。解决办法是把provider改成openai-compatible，用 Key 认证，不要走 OAuth 流程。TaoToken 的通道用 Key 认证即可，不需要 OAuth。
报错五：Skills 加载失败但无明确报错
[openclaw] skills loaded: 0没有报错但 Skills 数量是 0，通常是skill.json里的entry字段和实际文件名不匹配，或者parameters的 schema 格式不合法。用这个命令逐个验证：
for d in skills/*/; do echo "checking $d" node -e "JSON.parse(require('fs').readFileSync('$d/skill.json'))" && echo " json ok" done排查完这些，基本能覆盖 90% 的接入问题。如果还有别的报错，可以对照 TaoToken 的接入文档，里面有更详细的错误码说明。
6. 把通道固定下来：后续维护与扩展建议
跑通之后，有几件事值得做，能让这套配置更稳。
第一，把settings.json纳入版本管理，但 Key 不要提交。可以用环境变量替换：
{ "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "modelId": "claude-sonnet-4-20250514" } }启动前export TAOTOKEN_API_KEY=你的Key，这样配置文件可以安全地提交到仓库。
第二，Skills 目录可以按业务拆分。比如skills/office/、skills/dev/，只要settings.json里skills.dir指向根目录，OpenClaw 会递归扫描。每个 Skill 保持独立目录和skill.json，方便单独更新。
第三，如果你要长期跑 Agent 任务，可以考虑用 Coding Plan 这类按量方案，比单次调用更划算。入口在 Coding Plan 页面。日常调试模型响应，用模型对话页面直接测更快。
第四，定期检查 OpenClaw 和 Skills 的版本。Skills 的skill.json里可以声明兼容的 OpenClaw 版本范围，升级前先看 changelog，避免 schema 变更导致加载失败。
这套配置我跑了一段时间，整体稳定。核心就是三件事：settings里的 Base URL、Key、Model ID 对齐，Skills 目录结构规范，验证分三层做。把这三件事固定成流程，后面换模型、加 Skill 都不会乱。
