2026 OpenClaw（小龙虾）全攻略：从入门安装到深度解析，一篇吃透全网最火 AI Agent

1. 为什么你的 OpenClaw 装完就卡在“模型未配置”OpenClaw社区昵称“小龙虾”是一个开源的 AI Agent 框架能让你用微信、Telegram、飞书这类日常聊天工具给电脑下发指令让 AI 自主读写文件、执行命令、操控浏览器。它适合想快速跑通一个能“真干活”的 Agent、又不想从零写调度逻辑的开发者。但很多人卡在同一个地方安装脚本跑完了openclaw gateway也起来了一对话就报No model provider configured或者401 invalid api key。我试过在 macOS、Ubuntu 和 Windows 三台机器上部署踩过的坑集中在两处一是模型通道没配好二是配置文件字段写错。这篇就按“本地部署全流程”来给你能直接复制的config.toml和settings.json骨架并演示怎么用 TaoToken 的统一 Key 把模型通道接上最后附启动自检和报错排查动作。先说清楚 OpenClaw 的定位它本身不是大模型而是架在你和大模型之间的智能体中间件。它负责组装上下文、调用模型、执行工具、把结果回灌给模型循环到任务完成。所以它必须有一个稳定的模型 API 通道这个通道配不对后面所有技能都跑不起来。2. TaoToken 前置把模型通道统一成一条OpenClaw 支持多家模型提供商但如果你同时想用 Claude、GPT、Gemini 或者国产模型逐个配 Key 会很乱。TaoToken 提供的是统一 Key / API 通道一个 Key 走多家模型对 OpenClaw 这种需要频繁切换模型的 Agent 场景比较省事。你需要先拿到两样东西一个 API Key和一个 Base URL。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。Key 在控制台的 API Keys 页面创建创建后复制出来先粘到记事本确认是单行、没有换行符和多余空格——这是后面 90% 配置失败的直接原因。拿到之后OpenClaw 的模型配置有两种写法写在config.toml里或者写在settings.json里。下面两节分别给骨架。如果你还没创建 Key可以先到模型对话页面确认通道连通再回来配 OpenClaw。注意Key 不要明文提交到 Git 仓库建议用环境变量注入配置文件里只写变量名。3. 可复制配置config.toml 与 settings.json 骨架3.1 config.toml 骨架OpenClaw 的主配置一般放在~/.openclaw/config.toml。下面这份是接 TaoToken 统一通道的最小可用骨架字段名按你实际版本为准重点是base_url和api_key两处。# ~/.openclaw/config.toml [gateway] port 18789 host 127.0.0.1 [model] # 统一走 TaoToken 通道 provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 默认模型按你账号可用模型改 default_model claude-sonnet-4-20250514 timeout_seconds 120 [model.fallback] # 主模型失败时的兜底 enabled true model gpt-4o-mini [memory] long_term true short_term_days 7 [skills] auto_load true require_approval trueprovider写openai-compatible是因为 TaoToken 的接口兼容 OpenAI 的请求格式OpenClaw 里选这个类型就能对接。api_key用${TAOTOKEN_API_KEY}引用环境变量启动前先export TAOTOKEN_API_KEY你的Key。3.2 settings.json 骨架有些版本或插件读取的是settings.json放在~/.openclaw/settings.json。这份骨架和上面等价二选一即可不要两份都写导致字段冲突。{ gateway: { port: 18789, host: 127.0.0.1 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, defaultModel: claude-sonnet-4-20250514, timeoutSeconds: 120 }, skills: { autoLoad: true, requireApproval: true }, memory: { longTerm: true, shortTermDays: 7 } }两份配置的字段命名风格不同TOML 用下划线JSON 用驼峰。改的时候别混用否则 OpenClaw 启动时会报unknown field。3.3 环境变量与启动配置写好后注入 Key 再启动网关export TAOTOKEN_API_KEY你的Key openclaw gateway --port 18789如果你想让配置持久化把export那行写进~/.zshrc或~/.bashrc重开终端生效。Windows 用 PowerShell 的话$env:TAOTOKEN_API_KEY你的Key openclaw gateway --port 187894. 验证请求确认通道真的通了配置写完不代表通了必须做一次真实请求验证。OpenClaw 自带doctor和onboard两个命令先用它们做静态检查再用一次对话做动态验证。4.1 静态自检openclaw doctor正常输出会逐项列出 gateway、model、memory、skills 的状态。重点看 model 那一行如果显示provider: openai-compatible, base_url: https://taotoken.net/api说明配置被读到了。如果显示not configured回去检查配置文件路径和字段名。4.2 动态验证启动网关后用 CLI 发一条测试消息openclaw chat --message 只回复两个字通了如果返回“通了”说明模型通道、Key、Base URL 三者都对。如果返回 401是 Key 问题返回 404是 Base URL 写错返回超时检查网络和timeout_seconds。4.3 用 curl 单独验证通道想排除 OpenClaw 本身的干扰可以直接打 TaoToken 的接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道没问题问题在 OpenClaw 配置侧。这一步能帮你快速定位是通道挂了还是框架配错了。5. 本篇常见错排查5.1 报错No model provider configured最常见。原因通常是配置文件没被读到或者字段名写错。先确认文件路径ls ~/.openclaw/看有没有config.toml或settings.json。再确认字段TOML 里是base_urlJSON 里是baseUrl写反了不报错但读不到。5.2 报错401 invalid api keyKey 复制时带了换行或空格。把 Key 粘到记事本开“显示不可见字符”确认是单行。另外确认环境变量真的注入了echo $TAOTOKEN_API_KEY看有没有值。如果用了${TAOTOKEN_API_KEY}但没 exportOpenClaw 会拿到空字符串。5.3 报错404 not foundBase URL 写成了https://taotoken.net/api/带尾斜杠或者写成了https://taotoken.net/api/v1。OpenClaw 会自己拼/v1/chat/completions所以 Base URL 只写到/api就行。5.4 网关起来了但对话没反应检查require_approval是不是设成了true且没有审批入口。高危操作审批是安全特性但如果你在纯测试环境可以先设false跑通流程再改回true。另外确认port没被占用lsof -i :18789。5.5 升级后配置失效OpenClaw 版本更新较快旧配置键可能不再自动迁移。升级后先跑openclaw doctor --fix它会尝试修复已知的字段变更。如果还不行对照官方文档的配置章节手动改。6. 跑通之后把通道用起来通道通了接下来就是让 OpenClaw 真正干活。你可以先在微信或 Telegram 里接上它发一条“帮我在桌面创建一个 test.txt写入当前时间”看它能不能自主完成。这一步能验证工具执行链路是否正常。如果你打算长期跑编码类或 Agent 类任务建议把模型通道固定成 TaoToken 的统一入口再按任务类型在default_model和fallback之间切换。需要看当前可用模型和额度去模型对话页面要管理 Key 和配额去 API Keys 页面接入细节和字段说明看接入文档。长期编码或 Agent 场景可以直接上 Coding Plan省得每次手动切模型。最后提醒一句OpenClaw 权限很高能读写文件、执行命令。测试阶段先装在闲置设备上require_approval保持开启别一上来就给全盘权限。跑通流程比跑满功能重要。