1. 为什么 Windows 开发者第一次配 OpenClaw 总会卡在 CLI 与 Gateway
OpenClaw 是一个把大模型能力接到本地命令行与网关服务上的开源工具，你可以把它理解成「一个跑在自己机器上的 AI 调度中枢」：CLI 负责发指令、跑任务，Gateway 负责把请求转发给模型、管理会话和渠道。它适合谁？适合想在本地做 Agent、自动化脚本、多渠道机器人，又不想被各家 API Key 管理搞晕的开发者。
但真正上手时，Windows 用户最容易踩的坑不是模型本身，而是环境。原生 Windows 下 Node 版本、路径分隔符、后台服务注册经常互相打架，官方文档也明确建议走 WSL2。我试过在纯 Windows 里折腾 systemd 等价物，最后还是在 WSL2 的 Ubuntu 里十分钟跑通。
另一个高频卡点是 Key 管理。OpenClaw 的 CLI 和 Gateway 是两套配置入口：CLI 读config.toml，Gateway 侧的 Control UI 和部分渠道读settings.json。如果两边各填一个 Key，改一次要动两个文件，排查时根本不知道是哪边没生效。这篇就围绕「用 TaoToken 统一 Key/API 通道」这个思路，把 Windows + WSL2 下的首次配置一次讲透，包括可复制的配置骨架、一条连通性验证命令，以及报错怎么查。
核心检索词先明确：OpenClaw CLI 与 Gateway 配置、WSL2 环境接入、统一 API Key。下面所有步骤都在 WSL2 Ubuntu 22.04 + Node 22 上实测过。
2. 前置准备：WSL2、Node 22 与 TaoToken 统一 Key 通道
先说环境。WSL2 的安装不在本文展开，装好后在 Ubuntu 里执行node -v，必须 ≥ 22。低于这个版本 OpenClaw 的依赖会报ERR_REQUIRE_ESM之类的错。如果版本不对，用 nvm 切：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 node -v # 期望输出 v22.x.xpnpm 是可选的，但从源码构建时推荐装：npm install -g pnpm。
接下来是 Key 通道。TaoToken 在这里扮演的角色是「统一入口」：你只需要在它那边拿到一个 API Key，然后把 Base URL 指向https://taotoken.net/api，CLI 和 Gateway 都复用这一份凭证。这样做的直接好处是——换模型、换额度、查用量都只在一个地方操作，不用在 OpenClaw 的两个配置文件里来回同步。
拿 Key 的路径很直接：进控制台创建 API Key，复制出来先存到环境变量里，避免明文写进配置文件被 git 带走：
echo 'export TAOTOKEN_API_KEY="sk-你的key"' >> ~/.bashrc source ~/.bashrc echo $TAOTOKEN_API_KEY # 确认能打印出来模型 ID 也要提前确认。TaoToken 的模型列表在文档里有对照表，常见的有claude-sonnet-4-5、gpt-4o这类。你先把要用的 Model ID 记下来，下一步写配置时直接填。这里强调一点：Base URL、API Key、Model ID 这三件套必须成套出现，缺一个都会在验证阶段报 401 或 model not found。
注意：不要把 Key 直接写进会提交到仓库的文件。用环境变量引用，配置文件里写
${TAOTOKEN_API_KEY}这种占位形式，OpenClaw 支持读取环境变量。
环境齐了、Key 到手了，就可以进配置文件环节。
3. 可复制配置：config.toml 与 settings.json 骨架
OpenClaw 的配置分两处，这是新手最容易混的地方。CLI 侧主配置在~/.openclaw/config.toml，Gateway 侧和 Control UI 相关的运行时配置在~/.openclaw/settings.json。两个文件都要指向同一个 TaoToken 通道，才能做到「统一 Key」。
先建目录并写config.toml：
mkdir -p ~/.openclaw cat > ~/.openclaw/config.toml <<'EOF' # OpenClaw CLI 主配置 [gateway] host = "127.0.0.1" port = 18789 auth_token = "${OPENCLAW_GATEWAY_TOKEN}" [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" model_id = "claude-sonnet-4-5" timeout_seconds = 120 [agents.defaults] workspace = "~/.openclaw/workspace" sandbox_mode = "non-main" EOF这里provider用openai-compatible是因为 TaoToken 的 API 走 OpenAI 兼容协议，CLI 侧不需要额外适配层。base_url结尾不要带/v1，OpenClaw 会自己拼路径，多写一段会变成/v1/v1/chat/completions直接 404。
再写settings.json，给 Gateway 和 Control UI 用：
{ "gateway": { "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "modelId": "claude-sonnet-4-5" }, "connect": { "params": { "auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" } } }, "routing": { "agents": { "main": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } } } } }routing.agents.main.sandbox.mode设成off是为了让主智能体始终跑在主机上，群组和渠道会话才走沙箱隔离。如果你希望主智能体也被隔离，改成non-main即可。
Gateway 的 auth token 单独生成一个，别和 API Key 混用：
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 24) echo 'export OPENCLAW_GATEWAY_TOKEN="'"$OPENCLAW_GATEWAY_TOKEN"'"' >> ~/.bashrc两个文件写完后，用openclaw config validate检查语法。如果提示某个字段未知，多半是版本差异，对照openclaw config schema的输出调整。配置这一步做扎实，后面验证会顺很多。
4. 启动 Gateway 并验证连通性：一条命令确认 Node 与 Gateway 正常
配置就绪后，先启动 Gateway。前台跑方便看日志：
openclaw gateway --port 18789 --verbose看到Gateway listening on 127.0.0.1:18789就说明服务起来了。另开一个 WSL2 终端做验证。最直接的一条连通性命令是：
openclaw health --deep预期返回类似：
{ "status": "ok", "gateway": "reachable", "model": { "provider": "openai-compatible", "model_id": "claude-sonnet-4-5", "auth": "valid" }, "node": "v22.11.0" }重点看三个字段：gateway是reachable、auth是valid、node版本 ≥ 22。三个都对，说明 CLI 到 Gateway 到 TaoToken 这条链路全通了。
如果health显示auth: unconfigured，说明环境变量没被读到。检查echo $TAOTOKEN_API_KEY是否有值，以及启动 Gateway 的终端是否 source 过~/.bashrc。环境变量是在进程启动时读取的，改完要重启 Gateway。
再补一条端到端测试，直接发一条消息：
openclaw message send --target main --message "ping from openclaw"返回里带message_id和status: delivered就成功了。这一步同时验证了 Node 运行时和 Gateway 的会话路由。
Control UI 也可以顺手确认：浏览器打开http://127.0.0.1:18789/，在设置里粘贴OPENCLAW_GATEWAY_TOKEN的值，能进聊天界面并收到回复，说明 Gateway 侧配置也生效了。到这一步，你的 OpenClaw 已经是一个可用的本地 AI 中枢了。
5. 常见报错排查：401、local proxy failed 与 reading choices
配置阶段报错基本集中在几个固定位置，对照着查能省很多时间。
401 Unauthorized：最常见。原因通常是 Key 没读到或 Base URL 写错。先确认echo $TAOTOKEN_API_KEY有值，再确认config.toml里base_url是https://taotoken.net/api且没有多余斜杠。如果 Key 是从别处复制带空格，用echo -n "$TAOTOKEN_API_KEY" | wc -c看长度对不对。
local proxy failed / connection refused：Gateway 没起来，或者端口被占。用openclaw gateway status看状态，ss -tlnp | grep 18789看端口。WSL2 里如果之前用--install-daemon装过服务，可能有个旧进程占着端口，openclaw gateway stop再重启。
reading choices / cannot read property 'choices'：这是响应结构解析失败，几乎都是 Base URL 多写了/v1，导致请求打到了错误路径返回了非预期 JSON。把base_url改回https://taotoken.net/api即可。另一个可能是 Model ID 拼错，TaoToken 返回了错误对象而不是标准 completion 结构。
OAuth 相关报错：如果你在向导里选了 OAuth 而不是 API Key，凭证会存在~/.openclaw/credentials/oauth.json。无头环境下 OAuth 容易失败，建议直接用 API Key 路径，也就是本文这套配置。真要复用 Claude Code 凭证，用claude setup-token生成后再填。
Node 版本报错：ERR_REQUIRE_ESM或Unsupported engine，都是 Node < 22。nvm use 22后重启 Gateway。
排查时有个万能命令：openclaw status --all，它输出一份只读的完整调试报告，可以直接贴出来对照。养成先跑它的习惯，比逐条猜快得多。
6. 把统一 Key 用起来：从验证到日常编码与 Agent
链路通了之后，日常使用其实就围绕一个 Key 展开。CLI 侧跑任务、Gateway 侧接渠道、Control UI 里聊天，全都复用TAOTOKEN_API_KEY，改额度或换模型只动一处。
如果你要长期跑编码类任务或 Agent，建议把模型和额度规划一下，用 Coding Plan 这类方案比按次调用更划算，适合持续性的开发场景。想先验证不同模型的表现，可以直接在模型对话里试，确认哪个 Model ID 最合你的任务再写进配置。
接入文档里有完整的参数说明和模型对照表，遇到字段不确定时以文档为准。API Key 的创建和管理都在控制台完成，建议给不同项目建不同的 Key，方便单独吊销和统计用量。
最后留一个实用习惯：把~/.openclaw/config.toml和settings.json纳入版本管理时，用.gitignore排除真实 Key，只提交带${}占位符的模板。这样换机器时复制模板、重设环境变量就能恢复，不会因为一次误提交把 Key 泄露出去。
