1. OpenClaw 3.0.2 升级后 Gateway 离线与启动慢的真实场景
OpenClaw 3.0.2 是一个把大模型思考能力落到本地执行的智能体框架，Gateway 是它内部负责调度模型请求、管理会话与工具调用的常驻服务。你升级到 3.0.2 之后，如果发现主界面右上角一直显示「Gateway 离线」，或者每次冷启动都要转圈一两分钟才进对话界面，那基本可以确定是 Gateway 进程没起来、起来了又掉、或者起来了但握手超时。这三个现象在日志里长得完全不一样，排查方向也完全不同，所以第一步不是急着重装，而是先把「离线」和「慢」拆开看。
我见过最多的场景是这样的：安装路径里带了中文，比如D:\个人AI工具\OpenClaw，程序能装完，但 Gateway 启动时读取.env里的路径参数直接抛异常，进程秒退，界面就显示离线。还有一种更隐蔽的，路径是纯英文，但安全软件把 Gateway 的可执行文件当成可疑程序，启动瞬间被拦截，日志里只留下一行spawn EPERM，不仔细看根本发现不了。启动慢则通常是另一回事：3.0.2 首次运行会初始化向量索引和浏览器自动化组件，如果磁盘是机械盘或者杀软在实时扫描每一个新生成的文件，初始化时间会被拉长到 1-3 分钟，这属于正常范围，但超过 3 分钟还在转圈，就要查端口占用和依赖版本了。
这篇清单按「日志 → 端口 → 配置」三处切入，每一处都给出可复制的命令和配置片段，你跟着做就能在本地复现并确认修复效果。适合已经装好 OpenClaw 3.0.2、但被 Gateway 离线或启动慢卡住的用户，也适合准备升级到 3.0.2 想提前避坑的人。下面所有命令都在 Windows 10/11 的 PowerShell 里实测过，Mac 和 Linux 的对应命令我会在需要的地方标注。
先明确一个判断标准：Gateway 在线时，主界面右上角会显示「Gateway 在线」，并且你能在日志里看到Gateway listening on 127.0.0.1:xxxx这样的行。如果只有界面显示离线，但日志里连监听行都没有，说明进程根本没启动成功；如果有监听行但界面还是离线，说明是前端和 Gateway 之间的握手失败，方向又不一样。把这个判断标准记住，后面每一步排查都会用到。
2. TaoToken 前置准备：给 Gateway 配一个稳定的模型入口
OpenClaw 3.0.2 的 Gateway 本身不产出模型能力，它要把请求转发给一个兼容 OpenAI 协议的后端。很多「Gateway 离线」的根因其实不在 Gateway 进程，而在它启动时要去拉模型列表或做健康检查，后端连不上，Gateway 就卡在初始化阶段，界面自然显示离线。所以排查 Gateway 之前，先把模型入口配好，能排除掉一大半误判。
我目前用的是 TaoToken 作为模型入口，它的 API 地址是https://taotoken.net/api，兼容 OpenAI 的/v1/chat/completions和/v1/models接口，OpenClaw 的 Gateway 可以直接把它当成 OpenAI 后端来配。你需要先去控制台拿一个 API Key，地址是https://taotoken.net/console，登录后在 API Keys 页面创建一个新 Key，复制出来备用。这个 Key 就是后面配置里要填的api_key字段。
拿到 Key 之后，建议先用一条 curl 命令确认这个入口本身是通的，再去配 OpenClaw。这样如果后面 Gateway 还是离线，你就能确定问题在 OpenClaw 侧而不是模型侧。命令如下，把sk-你的Key替换成实际值：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 8 }'如果返回里能看到choices数组和一段回复内容，说明 Key 和网络都没问题。如果返回 401，说明 Key 复制错了或者被禁用；如果返回model not found，说明你填的模型 ID 不在这个入口的支持列表里，换一个再试。这一步花两分钟，能帮你省掉后面半小时的瞎猜。
TaoToken 的模型对话入口在https://taotoken.net/models，你可以在那里先手动聊两句，确认账号状态正常。如果你打算长期跑编码类 Agent 任务，可以看下 Coding Plan 页面https://taotoken.net/coding-plan，它针对高频调用做了额度优化，比按量计费更适合 OpenClaw 这种会反复调模型的场景。接入文档在https://taotoken.net/doc，里面有完整的 Base URL、鉴权方式和模型 ID 列表，配 OpenClaw 时对着抄就行。
这里要提醒一句：OpenClaw 的 Gateway 在启动时会调用/v1/models做一次健康检查，如果你的模型入口不支持这个接口，Gateway 可能会卡在初始化。TaoToken 的/api/v1/models是支持的，所以配上去之后 Gateway 启动会顺畅很多。如果你用的是别的入口，先确认它支持/v1/models，不支持的话在 OpenClaw 配置里把健康检查关掉，具体字段后面配置章节会讲。
3. 可复制配置：OpenClaw 3.0.2 的 Gateway 配置文件怎么写
OpenClaw 3.0.2 的 Gateway 配置主要落在两个文件里：安装目录下的.env和config/gateway.json。.env管环境变量和路径，gateway.json管服务端口、模型后端和超时参数。升级后出问题，十有八九是这两个文件里的字段和 3.0.2 的新格式对不上。下面给出我实测可用的完整片段，你直接替换成自己的值就能用。
先看.env，路径是D:\OpenClaw\.env（假设你装在 D 盘纯英文路径）。重点字段是OPENCLAW_HOME和GATEWAY_PORT，前者必须是纯英文路径，后者如果和别的服务冲突就换一个：
# OpenClaw 3.0.2 环境配置 OPENCLAW_HOME=D:\OpenClaw GATEWAY_HOST=127.0.0.1 GATEWAY_PORT=18789 GATEWAY_LOG_LEVEL=info GATEWAY_STARTUP_TIMEOUT=120 MODEL_BASE_URL=https://taotoken.net/api MODEL_API_KEY=sk-你的Key MODEL_DEFAULT=gpt-4o-mini BROWSER_AUTOMATION=true VECTOR_INDEX_ON_START=true这里GATEWAY_STARTUP_TIMEOUT=120是关键，3.0.2 默认是 60 秒，首次启动初始化向量索引经常超过 60 秒，Gateway 会自己判定超时然后退出，界面就显示离线。把它调到 120 或 180，能解决相当一部分「首次启动就离线」的问题。VECTOR_INDEX_ON_START如果你不需要语义检索，可以设成false，启动速度会快很多。
再看config/gateway.json，路径是D:\OpenClaw\config\gateway.json。这个文件管模型后端和健康检查，3.0.2 的格式和 2.x 有区别，model字段从字符串变成了对象：
{ "gateway": { "host": "127.0.0.1", "port": 18789, "startupTimeout": 120, "healthCheck": { "enabled": true, "path": "/v1/models", "intervalMs": 30000 } }, "model": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "defaultModel": "gpt-4o-mini", "timeoutMs": 60000 }, "logging": { "level": "info", "file": "logs/gateway.log" } }注意healthCheck.path是/v1/models，TaoToken 支持这个路径，所以保持enabled: true没问题。如果你用的模型入口不支持/v1/models，把enabled改成false，Gateway 启动时就不会去拉模型列表，能避免卡在初始化。model.timeoutMs设成 60000，给模型响应留足时间，避免 Gateway 因为单次请求超时误判后端不可用。
如果你用的是 Claude Code 类的接入方式，OpenClaw 3.0.2 也支持通过settings.json指定模型入口。路径在%USERPROFILE%\.openclaw\settings.json，内容如下：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-3-5-sonnet-20241022" } }这三个字段——Base URL、Key、Model ID——是接入的三件套，缺一个 Gateway 就可能在启动时握手失败。Base URL 填https://taotoken.net/api，Key 填你创建的那个，Model ID 填 TaoToken 文档里列出的可用模型。填完之后，Gateway 启动时会优先读这个文件，覆盖.env里的同名配置。
配置改完记得完全退出 OpenClaw（不是关窗口，是在托盘图标右键退出），再重新启动，否则旧进程还占着端口，新配置不生效。这一步很多人漏掉，然后说「改了没用」，其实是进程没重启。
4. 验证请求：确认 Gateway 真的在线且启动变快
配置改完之后，不要只看界面右上角的文字，那个状态有缓存，可能滞后十几秒。最可靠的验证方式是直接请求 Gateway 的本地端口，看它有没有正常响应。OpenClaw 3.0.2 的 Gateway 默认监听127.0.0.1:18789，你可以用 curl 或 PowerShell 的Invoke-RestMethod来测。
先测健康检查接口，这个接口不需要鉴权，返回 200 就说明 Gateway 进程活着：
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/health如果返回200，说明 Gateway 在线。如果返回000或连接被拒绝，说明进程没起来，回到日志章节查原因。如果返回401，说明健康检查接口需要鉴权，检查gateway.json里的healthCheck配置。
再测模型转发是否正常，这一步会真正走一次模型调用，能同时验证 Gateway 和 TaoToken 入口：
curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Gateway 测试"}], "max_tokens": 16 }'如果返回里有choices和一段回复，说明整条链路通了：OpenClaw Gateway 收到请求 → 转发给 TaoToken → 拿到模型回复 → 返回给你。如果返回502或model backend unreachable，说明 Gateway 活着但连不上模型入口，检查gateway.json里的baseUrl和apiKey是否和.env一致。如果返回reading choices相关的错误，说明模型入口返回的格式 Gateway 解析不了，通常是模型 ID 填错了，换成 TaoToken 文档里明确列出的 ID。
启动速度的验证要分两次看。第一次冷启动，从双击启动程序到界面显示「Gateway 在线」，用秒表记一下时间。3.0.2 首次启动因为要建向量索引，1-2 分钟是正常的，超过 3 分钟就要查端口占用。第二次启动，完全退出后再启动，这时候索引已经建好，正常应该在 10 秒内进界面。如果第二次还是超过 30 秒，说明有别的进程在抢端口或者杀软在扫描，继续往下看排障章节。
日志里也能看到启动耗时。打开D:\OpenClaw\logs\gateway.log，找Gateway started in XXXms这一行，XXX 就是实际启动毫秒数。正常冷启动在 60000-120000ms 之间，热启动在 3000-8000ms 之间。如果冷启动超过 180000ms，基本可以确定是磁盘或杀软的问题，不是配置问题。
验证通过之后，你可以去 TaoToken 的模型对话页面https://taotoken.net/models对照一下，确认 Gateway 转发的请求确实到了你的账号下。如果那边能看到调用记录，说明链路完全打通，可以放心跑任务了。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错来，每个报错给出触发条件和修复动作。你遇到哪个就查哪个，不用全看。
401 Unauthorized。触发条件：Gateway 启动时调/v1/models或转发请求时，模型入口返回 401。根因通常是 Key 填错、Key 被禁用、或者.env和gateway.json里的 Key 不一致。修复动作：先确认.env里的MODEL_API_KEY和gateway.json里的model.apiKey是同一个值，然后去 TaoToken 控制台https://taotoken.net/api-keys确认这个 Key 状态是启用。如果 Key 没问题，检查请求头格式，TaoToken 要求Authorization: Bearer sk-xxx，Bearer 后面有一个空格，少空格也会 401。
local proxy failed。触发条件：Gateway 尝试连接模型入口时，本地网络层就失败了，根本没到 TaoToken。根因通常是系统代理设置干扰、DNS 解析失败、或者防火墙拦了出站连接。修复动作：先确认你能用 curl 直接访问https://taotoken.net/api/v1/models，如果 curl 也失败，说明是网络层问题，检查系统代理设置，把127.0.0.1和localhost加入代理例外。如果 curl 成功但 Gateway 失败，说明 Gateway 进程没继承系统代理设置，在.env里加一行NO_PROXY=127.0.0.1,localhost，让 Gateway 直连本地端口。
reading choices 报错。完整报错通常是error reading choices: unexpected end of JSON input或cannot unmarshal choices。触发条件：Gateway 收到了模型入口的响应，但响应体不是预期的 OpenAI 格式。根因通常是模型 ID 填错，入口返回了一个错误对象而不是正常的choices数组。修复动作：把gateway.json里的defaultModel换成 TaoToken 文档里明确列出的模型 ID，比如gpt-4o-mini或claude-3-5-sonnet-20241022。改完重启 Gateway，再跑一次第 4 节的验证请求。
OAuth 相关报错。完整报错可能是OAuth token expired或failed to refresh OAuth token。触发条件：你用的是需要 OAuth 的模型入口，token 过期了。修复动作：如果你用的是 TaoToken 的 API Key 方式，不会遇到这个错，因为 API Key 不走 OAuth。如果你确实在用 OAuth 入口，去对应控制台重新授权，拿到新 token 后更新到settings.json的ANTHROPIC_API_KEY字段。OpenClaw 3.0.2 对 OAuth 的支持还在完善中，建议优先用 API Key 方式接入。
端口占用导致启动慢。报错可能是EADDRINUSE: address already in use 127.0.0.1:18789。触发条件：上一个 Gateway 进程没退干净，或者别的服务占了这个端口。修复动作：用netstat -ano | findstr 18789找到占用进程的 PID，然后用taskkill /PID <PID> /F杀掉。如果不想杀，就在.env里把GATEWAY_PORT改成18790或别的空闲端口，同时更新gateway.json里的port字段，两处必须一致。
杀软拦截导致 spawn EPERM。报错在日志里是spawn EPERM或access denied。触发条件：Gateway 启动子进程时被安全软件拦截。修复动作：把D:\OpenClaw整个目录加入杀软白名单，包括实时防护和防火墙。如果已经被隔离了文件，去隔离区恢复，然后重新解压安装包覆盖。这一步做完必须完全重启 OpenClaw，否则白名单不生效。
每个报错修完之后，都回到第 4 节跑一遍验证请求，确认返回正常再继续用。不要一次改多个地方，否则出了问题不知道是哪个改动生效了。
6. 语义一致 CTA：把 Gateway 跑稳之后该做什么
Gateway 跑稳之后，OpenClaw 3.0.2 的本地自动化能力才能真正用起来。你可以开始跑文件整理、网页信息采集、文档解析这些任务，Gateway 会在后台调度模型和工具，你只需要在输入框里写自然语言指令。如果任务涉及大量模型调用，比如批量处理几百个文档，建议用 Coding Plan 的额度，比按量计费划算，入口在https://taotoken.net/coding-plan。
如果你在排障过程中发现是模型入口的问题，比如 401 或 reading choices，先去 API Keys 页面https://taotoken.net/api-keys检查 Key 状态，再对着接入文档https://taotoken.net/doc核对 Base URL 和模型 ID。文档里有完整的字段说明和示例，比在日志里猜快得多。想先手动验证模型是否正常，可以去模型对话页面https://taotoken.net/models聊两句，确认账号和模型都没问题，再回来配 OpenClaw。
长期跑编码类 Agent 任务的话，Coding Plan 页面https://taotoken.net/coding-plan有额度说明，适合 OpenClaw 这种会反复调模型的场景。控制台https://taotoken.net/console可以看调用记录和余额，Gateway 每次转发请求都会在那里留痕，排障时对照着看很方便。
最后提醒一个实操细节：OpenClaw 3.0.2 的 Gateway 日志默认只保留最近 7 天，如果你要长期排查，在gateway.json里把logging.level设成debug，日志会更详细，但文件增长也快，记得定期清理logs目录。Gateway 跑稳之后，把debug改回info，减少磁盘写入，启动也能快一点。
