1. 为什么我劝你先搞懂 OpenClaw 再动手装OpenClaw圈里人叫它“小龙虾”是一个本地优先的开源 AI Agent 框架核心能力是让大模型从“只会聊天”变成“能动手干活”读写本地文件、跑 Shell 命令、控制浏览器、调 API、按计划执行任务。它适合三类人想把重复办公流程自动化的普通用户、想给自己项目加一个本地助理的开发者、以及在意数据不出本机、不想把敏感文件传到云端的团队。但很多人卡在第一步装完 CLI、跑起 gateway结果 Agent 一执行任务就报模型鉴权失败或者 Skills 加载不出来。问题往往不在 OpenClaw 本身而在模型通道没配通。这篇就按“环境准备 → Node.js 依赖 → 配置文件骨架 → TaoToken 统一 Key 接入 → 启动验证 → 报错排查”的完整链路走一遍配置片段可以直接复制改。我试过把模型通道单独抽出来统一管理后面换模型、加渠道都不用动 Agent 主配置省事很多。下面按这个思路展开。2. 环境准备与 Node.js 依赖别让版本问题拖后腿OpenClaw 对运行时版本有硬要求Node.js 低于 22 会在启动阶段直接抛错而且报错信息不一定直白。先把基础环境确认清楚能省掉后面一半的排查时间。2.1 版本与工具清单组件最低要求说明Node.js≥ 22低于此版本部分 ESM 特性不可用npm / pnpmnpm ≥ 10pnpm 更快可选Git任意较新版本克隆仓库或装 Skills 用操作系统Windows / macOS / Linux全平台支持先验证版本三条命令一次跑完node -v npm -v git --version如果node -v输出的是 v18 或 v20别急着装 OpenClaw先用 nvm 切版本# macOS / Linux 用 nvm nvm install 22 nvm use 22 # Windows 用 nvm-windows nvm install 22.14.0 nvm use 22.14.02.2 安装 OpenClaw 本体推荐用 npm 全局安装路径清晰、升级方便npm install -g openclawlatest openclaw --version装完先别急着 onboard确认一下全局 bin 目录在 PATH 里。Windows 上如果提示openclaw 不是内部或外部命令多半是 npm 全局目录没进环境变量用npm config get prefix看路径手动加进 PATH 即可。2.3 初始化配置骨架openclaw onboard --install-daemon这一步会生成默认配置目录通常在~/.openclaw/。初始化完成后目录结构大致是这样~/.openclaw/ ├── config.toml # 主配置 ├── agents/ │ └── main/ │ └── settings.json # Agent 级设置 ├── skills/ # 技能目录 └── logs/ # 运行日志注意不同版本目录名可能略有差异以openclaw doctor输出的实际路径为准。先跑一次openclaw doctor它会告诉你配置文件到底在哪、哪些依赖缺失。3. TaoToken 前置把模型通道统一成一个 KeyOpenClaw 的 Agent 大脑需要对接 LLM默认支持多家 provider。问题是每换一个模型就要改一次 apiKey、baseURL、model 名配置越堆越乱。更稳的做法是走统一通道一个 Key、一个 baseURL模型名按需切换。TaoToken 在这里扮演的就是这个统一入口。你可以在官网了解它的定位然后到控制台创建 Key。整个流程分三步第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并进入控制台。第二步在控制台里生成 API Key建议单独建一个给 OpenClaw 用方便后续按项目隔离和吊销。生成后立刻复制保存页面刷新后通常不再完整显示。第三步确认你要用的模型名。OpenClaw 里填的 model 字段必须和通道支持的模型标识一致写错会直接返回 404 或 model not found。拿到 Key 之后接入地址用 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 baseURL 使用。Key 的管理入口在控制台的 API Keys 页面接入细节可以对照接入文档两处配合看最清楚。提示不要把 Key 硬编码进会提交到 Git 的文件里。用环境变量或本地未跟踪的配置文件承载后面配置片段会演示。4. 可复制配置config.toml 与 settings.json 骨架这一节是全文的核心配置写对了后面基本一路顺。OpenClaw 的模型接入分两层主配置config.toml定义 provider 和通道Agent 级settings.json指定当前用哪个 profile。4.1 config.toml定义统一通道# ~/.openclaw/config.toml [gateway] port 18789 host 127.0.0.1 [providers.taotoken] # 统一通道baseURL 不带查询参数 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY type openai-compatible [agents.main] provider taotoken model claude-sonnet-4-6 temperature 0.3 max_tokens 4096 [skills] workspace_dir ./skills auto_load true这里有两个关键点。一是api_key_env指向环境变量名而不是把 Key 写死在文件里二是type用openai-compatible因为统一通道对外暴露的是兼容 OpenAI 协议的接口OpenClaw 按这个协议发请求即可。4.2 settings.jsonAgent 级参数{ agent: { name: main, profile: taotoken, model: claude-sonnet-4-6, system_prompt_file: ./prompts/soul.md, memory: { enable: true, layers: [soul, tools, user, session] } }, skills: { enabled: [file, browser, code, search], approval_required: [shell, file_delete] } }approval_required这一项建议保留涉及删文件、跑 Shell 这类敏感操作时强制人工确认避免 Agent 误操作。4.3 注入环境变量macOS / Linuxexport TAOTOKEN_API_KEY你的Key # 写入 shell 配置持久化 echo export TAOTOKEN_API_KEY你的Key ~/.zshrc source ~/.zshrcWindows PowerShell$env:TAOTOKEN_API_KEY 你的Key # 持久化到用户级环境变量 [Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User)4.4 Skills 加载配置Skills 分三层优先级Workspace项目专属 User个人全局 Bundled官方内置。加载顺序决定了同名技能谁覆盖谁。查看当前已加载的技能openclaw skill list安装一个社区技能openclaw skill install browser如果技能装完不生效先确认config.toml里auto_load true再检查技能目录是否在workspace_dir下。5. 启动验证从 gateway 到一次真实任务配置写完启动网关并验证请求是否真的通到模型。5.1 启动网关openclaw gateway --port 18789 --verbose--verbose会打印每次请求的 provider、model、耗时排查时非常有用。看到类似gateway listening on 127.0.0.1:18789就说明起来了。5.2 发一条测试消息openclaw agent --message 用一句话说明你现在用的是哪个模型如果返回正常文本说明 Key、baseURL、model 三者都对上了。如果返回鉴权错误往下看第 6 节。5.3 跑一个真实任务openclaw agent --message 列出当前目录下所有 .md 文件统计每个文件的行数这条指令会触发 file 技能Agent 需要先规划步骤、再调用工具、最后汇总结果。观察 verbose 日志你能看到 Observe → Think → Act → Check 的完整链路。如果 Agent 只回复“我无法访问文件”多半是 file 技能没启用回到settings.json的enabled列表补上。5.4 验证 Skills 是否真的加载openclaw skill list --verbose输出里会标注每个技能的来源层级workspace / user / bundled。如果某个技能显示not loaded检查它的依赖是否装齐部分技能需要额外的系统工具。6. 本篇常见报错排查这一节按报错现象归类遇到问题直接对号入座。6.1 鉴权失败401 / invalid api key现象是 Agent 一执行就返回 401。排查顺序先确认环境变量真的注入了echo $TAOTOKEN_API_KEYWindows 用echo $env:TAOTOKEN_API_KEY看有没有值再确认config.toml里api_key_env拼写和实际变量名完全一致大小写敏感最后确认 Key 没有多余空格或换行复制时容易带上。6.2 模型找不到404 / model not foundmodel 字段写错了。统一通道对模型标识有固定命名去控制台或接入文档核对准确名称别凭记忆写。改完config.toml后重启 gateway 才生效。6.3 连接超时ETIMEDOUT / ECONNREFUSED先确认 baseURL 是https://taotoken.net/api没有多余路径或参数。再检查本机网络能否正常访问该域名用 curl 快速验证curl -I https://taotoken.net/api如果 curl 也超时是网络层问题不是 OpenClaw 配置问题。6.4 Skills 加载失败现象是openclaw skill list里技能缺失或报错。检查三点技能目录权限是否可读auto_load是否为 true技能依赖的 Node 版本是否满足。部分社区技能要求 Node ≥ 22版本不够会静默失败。6.5 端口被占用EADDRINUSE18789 被别的进程占了。换端口启动openclaw gateway --port 18790 --verbose同时记得把config.toml里的port一起改掉否则其他组件还按旧端口找网关。6.6 Agent 不执行只回复Agent 收到指令却只给文字回复、不调工具通常是技能没启用或 system prompt 没引导它用工具。先openclaw skill list确认技能在再检查settings.json的enabled列表。如果技能都在看 verbose 日志里 Think 阶段有没有选出工具没选就是 prompt 或模型能力问题。7. 把通道固定下来后面才省心跑通之后建议把模型通道这件事固定成一套流程Key 只存在环境变量里baseURL 只写一次换模型只改model字段。这样无论你后面是接 IM 渠道、加定时任务还是装更多 Skills都不会因为模型配置变动而返工。需要长期跑编码类或 Agent 类任务的话可以了解 Coding Plan它更适合高频、持续调用的场景日常验证模型是否通、快速试一条指令用模型对话页面最直接Key 的创建和轮换都在 API Keys 页面接入参数对照接入文档。这几处配合起来基本覆盖从试用到稳定运行的全过程。最后留一个实用习惯每次改完config.toml或settings.json先跑openclaw doctor再启动 gateway。doctor 会把配置解析、依赖检查、端口占用一次性报出来比启动后看一堆日志再回头找问题快得多。