1. Windows 上跑 OpenClaw 到底卡在哪
OpenClaw（前身 Clawdbot）是一个本地优先、强执行能力的开源 AI 智能体，核心卖点是“真能干活”——你用自然语言下指令，它自己拆任务、调工具，在设备上完成文件读写、程序控制、多平台联动。它本身不含大模型推理能力，只是一个代理框架，必须外接云端 API（比如腾讯混元）或本地模型（比如 Ollama）才能解锁自然语言理解。适合谁？想在 Windows 上快速体验智能体、又不想折腾 Linux 双系统的开发者，以及需要数据不出内网的隐私敏感用户。
但 Windows 原生环境对 OpenClaw 的友好度确实不如 Linux 或 macOS。我实测下来，90% 的失败集中在三件事：Node.js 版本不对、Gateway 端口被占、模型上下文窗口不够。这篇就把这三类坑一次讲透，同时给出用 TaoToken 统一 Key 接入腾讯混元与本地模型的完整配置骨架，让你少走弯路。
先明确一个认知：OpenClaw 的工作闭环是“装环境 → 装主程序 → 配模型 API”。前两步是体力活，第三步才是决定它能不能真正干活的关键。下面按这个顺序展开，每一步都给可复制的命令和配置。
2. 前置准备：TaoToken 统一 Key 与模型接入
在配置 OpenClaw 之前，先把模型侧的 Key 准备好。这里推荐用 TaoToken 做统一入口，原因是它把腾讯混元、Claude、GPT 等多家模型的调用收敛成一套 OpenAI 兼容接口，OpenClaw 里只需要填一个 Base URL 和一个 Key，切换模型时不用改代码。
具体操作：打开 https://taotoken.net/api 对应的控制台，进入 API Keys 页面创建一个新 Key，复制保存。这个 Key 就是后面 config.toml 里要填的凭证。如果你还没决定用哪个模型，可以先在模型对话页面测一下腾讯混元的响应效果，确认可用再写进配置。
注意：Key 只显示一次，创建后立刻保存到本地密码管理器。不要直接贴在会提交到 Git 的配置文件里。
TaoToken 的接入文档里有各语言的调用示例，OpenClaw 走的是 OpenAI 兼容协议，所以 Base URL 填https://taotoken.net/api即可，路径部分 OpenClaw 会自动补/v1/chat/completions。这一点和直连腾讯混元官方接口的写法不同，后面配置章节会对比说明。
如果你打算长期跑编码类 Agent 任务，可以顺带了解 Coding Plan，它针对高频调用做了额度优化，比按量计费更划算。但本篇聚焦部署，先不展开。
3. 可复制配置：config.toml 与 settings.json 骨架
OpenClaw 的配置分两层：config.toml管 Gateway 和全局行为，settings.json管模型 provider 和凭证。两个文件默认都在C:\Users\<你的用户名>\.openclaw\下。下面给的是最小可用骨架，直接复制改 Key 就能跑。
先看config.toml：
[gateway] mode = "local" port = 18789 host = "127.0.0.1" [logging] level = "info" file = "logs/openclaw.log" [security] allow_shell = true workspace = "C:/Users/YourName/.openclaw/workspace"mode = "local"表示只监听本机，不对外暴露；port如果和别的服务冲突，改成 18790 之类即可，但记得同步改浏览器访问地址。workspace是智能体读写文件的沙箱目录，强烈建议单独建一个空目录，别指向你的文档或桌面。
再看settings.json，这是模型接入的核心：
{ "providers": { "taotoken": { "type": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "models": { "hunyuan": "hunyuan-turbo", "claude": "claude-sonnet-4-20250514" } }, "ollama-local": { "type": "openai-compatible", "base_url": "http://127.0.0.1:11434/v1", "api_key": "ollama", "models": { "qwen": "qwen2.5:7b-32k" } } }, "default_provider": "taotoken", "default_model": "hunyuan" }这里有两个 provider：taotoken走云端，ollama-local走本地。default_provider决定默认用哪个，想切本地模型时改这一行就行。注意 Ollama 的base_url结尾必须带/v1，这是最常见的配置错误之一。
如果你只想用腾讯混元，把ollama-local整段删掉也不影响运行。反过来，如果你追求数据完全不出内网，就把default_provider改成ollama-local，云端那段留着备用。
4. 验证请求：从 Gateway 启动到模型连通
配置写完，先别急着开 Web 控制台，按顺序验证三层：Gateway 是否起来、模型 provider 是否可达、端到端对话是否通。
第一步，启动 Gateway 并看状态：
openclaw gateway start openclaw gateway status正常输出应该是Running，并且监听127.0.0.1:18789。如果显示Stopped或报端口占用，先跳到第 5 章排查。
第二步，单独测模型连通性。OpenClaw 自带一个诊断命令：
openclaw doctor --check-model它会读取settings.json里的默认 provider，发一条最小请求。成功时你会看到类似provider=taotoken model=hunyuan-turbo latency=820ms的输出。如果这里报 401，说明 Key 错了；报 404，说明 base_url 或模型名不对。
第三步，端到端验证。打开浏览器访问http://127.0.0.1:18789，在对话框里输入一句“列出当前 workspace 目录下的文件”。如果 OpenClaw 调用了 shell 工具并返回文件列表，说明整条链路通了。这一步很关键，因为它同时验证了模型推理和工具执行两个环节。
实测下来，从零到这一步顺利的话大约 15 分钟。如果卡住，大概率是下面几类错误。
5. 本篇常见错排查
坑一：openclaw不是内部或外部命令。原因是 npm 全局安装路径没进 PATH。解决：关闭当前 PowerShell，用管理员身份重开；若仍不行，手动把C:\Users\<用户名>\AppData\Roaming\npm加到系统环境变量，重启终端。
坑二：Gateway 启动失败，18789 被占用。先查占用进程：
netstat -ano | findstr :18789拿到 PID 后在任务管理器结束，或者直接改config.toml里的port。新手建议改端口，别去动占用进程，免得误杀系统服务。
坑三：模型报context length exceeded。OpenClaw 要求模型上下文窗口至少 16000 tokens，而 Ollama 默认拉的模型往往只有 4096。必须手动扩展：
ollama pull qwen2.5:7b cd C:\Users\<你的用户名> @" FROM qwen2.5:7b PARAMETER num_ctx 32768 "@ | Out-File -Encoding ascii Modelfile ollama create qwen2.5:7b-32k -f Modelfile然后在settings.json里把模型名改成qwen2.5:7b-32k。这一步不做，本地模型基本没法用。
坑四：TaoToken 返回 401 或 403。检查 Key 是否复制完整（有时会漏掉末尾字符），以及base_url是否误写成带/v1的完整路径。TaoToken 的 Base URL 填https://taotoken.net/api即可，OpenClaw 会自己补全。如果还不行，去 API Keys 页面确认 Key 状态是否正常。
坑五：WSL2 里访问 Windows 本地服务失败。如果你把 OpenClaw 装在 WSL2 而 Ollama 装在 Windows，127.0.0.1在 WSL2 里指向的是 WSL 自己，不是宿主机。这时要把base_url改成宿主机的 WSL 网关 IP，或者反过来把 Ollama 也装进 WSL2。最省事的做法是两者装在同一侧。
排查顺序建议固定为：先openclaw logs follow看实时日志，再openclaw doctor自动检测，最后才手动翻配置文件。95% 的问题日志里都有明确线索。
6. 接入方式怎么选：TaoToken 与本地模型的取舍
排障和接入过程中如果遇到 Key 管理或协议兼容问题，直接去 API Keys 页面重新生成一个，再对照接入文档核对 base_url 写法，比反复猜要快得多。想先验证腾讯混元的实际效果再决定是否写进配置，可以在模型对话里发几条中文长指令，看它对工具调用的理解是否到位。
长期跑编码或 Agent 任务的话，Coding Plan 的额度模型比按量计费更可控，适合每天都有调用量的场景。而如果你只是偶尔用用，按量付费的 TaoToken 统一 Key 已经够用，没必要提前买套餐。
最后给一个我踩过的坑：别把workspace指向C:\Users\<用户名>根目录。OpenClaw 有 shell 执行权限，一旦模型误判指令，可能在你家目录里乱建文件。单独开一个空目录，定期备份settings.json，比事后恢复省心得多。
