1. 为什么 Windows 开发者第一次配 OpenClaw 总会卡在 CLI 与 GatewayOpenClaw 是一个把大模型能力接到本地命令行与网关服务上的开源工具你可以把它理解成「一个跑在自己机器上的 AI 调度中枢」CLI 负责发指令、跑任务Gateway 负责把请求转发给模型、管理会话和渠道。它适合谁适合想在本地做 Agent、自动化脚本、多渠道机器人又不想被各家 API Key 管理搞晕的开发者。但真正上手时Windows 用户最容易踩的坑不是模型本身而是环境。原生 Windows 下 Node 版本、路径分隔符、后台服务注册经常互相打架官方文档也明确建议走 WSL2。我试过在纯 Windows 里折腾 systemd 等价物最后还是在 WSL2 的 Ubuntu 里十分钟跑通。另一个高频卡点是 Key 管理。OpenClaw 的 CLI 和 Gateway 是两套配置入口CLI 读config.tomlGateway 侧的 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/apiCLI 和 Gateway 都复用这一份凭证。这样做的直接好处是——换模型、换额度、查用量都只在一个地方操作不用在 OpenClaw 的两个配置文件里来回同步。拿 Key 的路径很直接进控制台创建 API Key复制出来先存到环境变量里避免明文写进配置文件被 git 带走echo export TAOTOKEN_API_KEYsk-你的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.tomlGateway 侧和 Control UI 相关的运行时配置在~/.openclaw/settings.json。两个文件都要指向同一个 TaoToken 通道才能做到「统一 Key」。先建目录并写config.tomlmkdir -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结尾不要带/v1OpenClaw 会自己拼路径多写一段会变成/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 refusedGateway 没起来或者端口被占。用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 泄露出去。
1. 为什么 Windows 开发者第一次配 OpenClaw 总会卡在 CLI 与 GatewayOpenClaw 是一个把大模型能力接到本地命令行与网关服务上的开源工具你可以把它理解成「一个跑在自己机器上的 AI 调度中枢」CLI 负责发指令、跑任务Gateway 负责把请求转发给模型、管理会话和渠道。它适合谁适合想在本地做 Agent、自动化脚本、多渠道机器人又不想被各家 API Key 管理搞晕的开发者。但真正上手时Windows 用户最容易踩的坑不是模型本身而是环境。原生 Windows 下 Node 版本、路径分隔符、后台服务注册经常互相打架官方文档也明确建议走 WSL2。我试过在纯 Windows 里折腾 systemd 等价物最后还是在 WSL2 的 Ubuntu 里十分钟跑通。另一个高频卡点是 Key 管理。OpenClaw 的 CLI 和 Gateway 是两套配置入口CLI 读config.tomlGateway 侧的 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/apiCLI 和 Gateway 都复用这一份凭证。这样做的直接好处是——换模型、换额度、查用量都只在一个地方操作不用在 OpenClaw 的两个配置文件里来回同步。拿 Key 的路径很直接进控制台创建 API Key复制出来先存到环境变量里避免明文写进配置文件被 git 带走echo export TAOTOKEN_API_KEYsk-你的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.tomlGateway 侧和 Control UI 相关的运行时配置在~/.openclaw/settings.json。两个文件都要指向同一个 TaoToken 通道才能做到「统一 Key」。先建目录并写config.tomlmkdir -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结尾不要带/v1OpenClaw 会自己拼路径多写一段会变成/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 refusedGateway 没起来或者端口被占。用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 泄露出去。
