1. 为什么 Windows 上跑 OpenClaw 总卡在 Gateway 离线
如果你在 Windows 上折腾过 OpenClaw，大概率遇到过这两个画面：一个是右上角状态栏一直转圈，提示「正在等待 Gateway 就绪」，等十分钟还是灰的；另一个是刚双击启动程序，Windows Defender 或第三方安全软件直接弹窗把核心文件隔离了，程序还没跑起来就没了。
这两个问题看着像两个独立故障，其实根子上是一件事：OpenClaw 的 Gateway 是一个本地常驻服务，它需要监听本地端口、读写工作目录、调用键鼠模拟接口。Windows 的安全机制对「监听端口 + 模拟输入」这类行为天然敏感，一旦拦截规则命中，Gateway 进程起不来，前端界面自然显示离线。所以排障顺序应该是先解决拦截，再确认 Gateway 能正常拉起，最后才是接模型通道。
这篇面向的是在 Windows 上搭本地 AI 工具链的人，不管你用的是 Win10 还是 Win11，只要你想让 OpenClaw 稳定跑起来、并且用一套统一的 Key 去接模型通道，下面的配置骨架和验证步骤都能直接抄。我会把 config.toml、settings.json 的关键片段给全，再配上启动日志检查、网关连通性测试、拦截规则回退确认这三步验证动作，目标是一次性跑通全链路。
需要提前说清楚：OpenClaw 本身是本地智能体框架，它负责调度和自动化执行，但模型推理能力得从外部通道来。我这边统一用 TaoToken 的 API 通道来供模型，一个 Key 管所有模型调用，省得在多个平台之间来回切。下面所有配置里的 Key 和地址都按这个来写。
2. TaoToken 前置准备：统一 Key 与通道地址
在动 OpenClaw 的配置文件之前，先把模型通道这块理清楚。TaoToken 的角色是提供统一的模型调用入口，你拿到一个 API Key 之后，OpenClaw 里所有需要模型推理的地方都指向同一个 base_url 和同一个 Key，不用为每个模型单独配一套凭证。
先做两件事。第一，去控制台创建一个 API Key，地址是 https://taotoken.net/api-keys ，创建完复制出来，后面要填进配置文件。第二，确认你要用的模型名称，TaoToken 的模型列表在文档里能查到，地址是 https://taotoken.net/doc ，选一个你常用的就行，比如做代码补全和 Agent 调度比较多的场景，选一个指令跟随能力强的模型。
这里有个容易踩的坑：很多人把 Key 直接写进 config.toml 然后提交到 Git，或者放在桌面文本文件里。建议的做法是 Key 只放在本地环境变量或者单独的 secrets 文件里，config.toml 里用引用方式读取。OpenClaw 支持从环境变量注入，下面配置片段里我会写成占位符形式，你替换成自己的实际值。
另外，TaoToken 的 API 基础地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 base_url 用。如果你后面要接 Claude Code 或者做长期编码任务，可以看下 Coding Plan 的说明，地址是 https://taotoken.net/coding-plan ，那个适合需要持续调用、按量计费的场景。普通对话和 Agent 调度用标准 API 通道就够了。
3. 可复制配置：config.toml 与 settings.json 骨架
OpenClaw 在 Windows 下的配置分两层：一层是 Gateway 服务本身的 config.toml，管监听地址、端口、工作目录、日志级别；另一层是模型通道的 settings.json，管 API 地址、Key、模型名、超时参数。两个文件都在安装目录的 config 子目录下，如果你解压后没看到，第一次启动会自动生成，但自动生成的默认值往往不对，需要手动改。
先看 config.toml 的骨架。这个文件控制 Gateway 能不能正常起来，重点在 host 和 port，以及 workspace 路径不能有中文和空格：
# config.toml - OpenClaw Gateway 服务配置 [gateway] host = "127.0.0.1" port = 18789 auto_start = true log_level = "info" log_file = "D:/OpenClaw/logs/gateway.log" [workspace] root = "D:/OpenClaw/workspace" temp_dir = "D:/OpenClaw/workspace/tmp" allow_symlink = false [security] # 拦截规则回退开关，排障阶段先设为 false strict_mode = false allowed_commands = ["file_ops", "browser", "keyboard_mouse"] blocked_paths = ["C:/Windows/System32", "C:/Program Files"] [gateway.health] check_interval = 5000 timeout = 3000几个关键点解释一下。host 必须是 127.0.0.1，不要写 0.0.0.0，否则 Windows 防火墙会额外弹窗拦截。port 默认 18789，如果你本机这个端口被占了，改成 18790 或更高，但改完记得同步改 settings.json 里的 gateway_url。workspace.root 用纯英文路径，我习惯放 D 盘，避免 C 盘权限问题。security.strict_mode 在排障阶段先设 false，等 Gateway 稳定在线了再考虑开严格模式，否则拦截规则会误伤正常的文件操作。
再看 settings.json，这个管模型通道：
{ "model_provider": { "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "model": "your-model-name", "timeout": 60000, "max_retries": 3 }, "gateway": { "url": "http://127.0.0.1:18789", "health_path": "/health", "reconnect_interval": 5000 }, "agent": { "max_steps": 20, "enable_browser": true, "enable_file_ops": true } }api_key 这里写的是环境变量引用 ${TAOTOKEN_API_KEY}，你在 Windows 里设置环境变量的命令是：
# PowerShell 中设置用户级环境变量 [Environment]::SetEnvironmentVariable("TAOTOKEN_API_KEY", "你的实际Key", "User")设置完要重启终端或者重启 OpenClaw 才能生效。model 字段填你在 TaoToken 文档里选好的模型名。timeout 给 60000 毫秒，Agent 调度有时候链路长，太短会频繁超时。gateway.url 必须和 config.toml 里的 host + port 对上，这是最容易配错的地方，一个写 18789 一个写 18790，Gateway 永远连不上。
4. 验证请求：三步确认全链路跑通
配置写完不是直接开界面看，而是按顺序做三步验证，每步都有明确的成功标志，哪步挂了就停在哪步排查，不要跳。
第一步，启动日志检查。用管理员身份打开 PowerShell，进到 OpenClaw 安装目录，手动拉起 Gateway 进程：
cd D:\OpenClaw .\openclaw-gateway.exe --config .\config\config.toml观察控制台输出，正常的话会依次打印这几行：
[INFO] gateway starting, host=127.0.0.1 port=18789 [INFO] workspace root loaded: D:/OpenClaw/workspace [INFO] security module initialized, strict_mode=false [INFO] gateway listening on 127.0.0.1:18789 [INFO] health endpoint ready at /health如果卡在 security module initialized 之后没有 listening，说明拦截规则还在生效，回到 config.toml 确认 strict_mode 是 false，并且检查 Windows Defender 的实时防护有没有把 openclaw-gateway.exe 加进排除项。如果直接报 port already in use，用 netstat 查一下谁占了 18789：
netstat -ano | findstr 18789找到 PID 后在任务管理器里结束对应进程，或者改 config.toml 的端口。
第二步，网关连通性测试。Gateway 起来之后，另开一个 PowerShell 窗口，用 curl 打健康检查接口：
curl http://127.0.0.1:18789/health正常返回是一个 JSON：
{"status":"ok","uptime":12,"workspace":"D:/OpenClaw/workspace","version":"2.9.3"}如果返回 connection refused，说明 Gateway 没起来或者端口不对。如果返回 403 或 401，说明安全模块拦截了本地请求，检查 config.toml 里 allowed_commands 有没有把 health 检查放进去，或者临时把 strict_mode 设 false 再试。
第三步，模型通道验证。Gateway 通了不代表模型能调通，这一步单独测 TaoToken 通道。用 curl 直接打 TaoToken 的 API：
curl -X POST https://taotoken.net/api/v1/chat/completions ` -H "Authorization: Bearer $env:TAOTOKEN_API_KEY" ` -H "Content-Type: application/json" ` -d '{\"model\":\"your-model-name\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":10}'返回里有 choices 字段且 content 有内容，说明 Key 和通道都正常。如果返回 401，检查环境变量有没有生效，在 PowerShell 里 echo $env:TAOTOKEN_API_KEY 看能不能打印出来。如果返回 model not found，回 TaoToken 文档确认模型名拼写。
三步都过了，再打开 OpenClaw 客户端，右上角应该显示「Gateway 在线」绿色标识。这时候下发一个简单指令测试，比如「在 D:/OpenClaw/workspace 下创建一个 test.txt 文件，内容写 hello」，看 Agent 能不能正常执行。执行成功说明全链路通了。
5. 本篇常见错排查
Q1：Gateway 一直显示离线，但手动启动进程没报错
这种情况多半是客户端和 Gateway 的端口配置不一致。检查 settings.json 里的 gateway.url 和 config.toml 里的 host + port 是否完全对应。另外确认客户端是不是以管理员身份运行的，非管理员权限下客户端可能连不上本地回环地址的某些端口。实测下来，把客户端和 Gateway 都用管理员权限启动，能解决大部分离线问题。
Q2：安全软件反复拦截，加了排除项还是被删文件
Windows Defender 的排除项要加两个地方：一是「病毒和威胁防护」里的排除项，把整个 OpenClaw 安装目录加进去；二是「勒索软件防护」里的受控文件夹访问，把 openclaw-gateway.exe 和客户端主程序加进允许列表。第三方安全软件比如火绒、360，除了加信任区，还要在「主动防御」或「行为拦截」里把 OpenClaw 相关进程设为允许。如果文件已经被隔离，先去隔离区恢复，再重新解压覆盖，不要直接重新安装，否则配置会丢。
Q3：模型调用返回 429 或超时
429 是限流，TaoToken 的标准通道有并发限制，如果你在 Agent 里开了多步并行，容易触发。把 settings.json 里的 max_retries 设成 3，timeout 设成 60000，让重试机制兜底。如果持续 429，去控制台看下当前用量，或者考虑切到 Coding Plan 通道，那个适合高频调用场景。超时的话先 curl 测一下通道本身的延迟，如果 curl 都快，那就是 OpenClaw 的 Agent 步骤太多，把 max_steps 从 20 降到 10 试试。
Q4：第一次启动卡在「正在等待 Gateway 就绪」超过 5 分钟
正常初始化是 1 到 3 分钟，超过 5 分钟基本是卡住了。先看 logs/gateway.log 最后几行，如果停在 loading dependencies，说明依赖组件没装全，重新跑一遍安装程序让它补齐。如果日志里反复出现 health check failed，说明 Gateway 进程起来了但健康检查没过，检查 workspace 目录权限，确保当前用户有读写权限。实在不行就完整关闭客户端和 Gateway 进程，删掉 workspace/tmp 下的临时文件，重新启动。
Q5：改了 config.toml 之后不生效
OpenClaw 的 Gateway 进程不会热加载配置，改完必须重启进程。而且如果你是通过客户端界面启动的 Gateway，改配置文件后要先在客户端里点「服务重启」，或者直接任务管理器结束 openclaw-gateway.exe 再重新启动客户端。另外注意 config.toml 的编码要是 UTF-8 无 BOM，用记事本改容易存成带 BOM 的格式，导致解析失败，建议用 VS Code 或 Notepad++ 改。
6. 接入文档与后续通道选择
全链路跑通之后，如果你要接更多模型或者做长期编码任务，可以看下 TaoToken 的接入文档，地址是 https://taotoken.net/doc ，里面有各语言的 SDK 示例和参数说明。日常调试模型效果，直接用模型对话页面最快，地址是 https://taotoken.net/chat ，不用写代码就能测通道通不通。
如果你打算把 OpenClaw 当成长期跑的 Agent 平台，每天都有大量模型调用，那 Coding Plan 更合适，地址是 https://taotoken.net/coding-plan ，按量计费，不用担心标准通道的并发限制。控制台在 https://taotoken.net/console ，用量和 Key 管理都在那里。API Key 创建页再放一次：https://taotoken.net/api-keys ，忘了在哪建的可以直接收藏这个。
最后说个实际经验：OpenClaw 的 Gateway 稳定性跟 Windows 的电源管理也有关系。如果你用的是笔记本，合盖休眠再打开，Gateway 进程有时候会假死，健康检查超时但进程还在。解决办法是在电源选项里把「合盖时」设为「不采取任何操作」，或者把 OpenClaw 相关进程加到「阻止系统进入睡眠」的列表里。这个坑我踩过，排查了半天以为是配置问题，结果是系统休眠把服务挂起了。
