企业官网建设流程全解析

1. Windows 部署 OpenClaw 总报错？先把 Gateway 离线这件事讲透

OpenClaw 是一个跑在本地桌面上的 AI 智能体工具，能读写本地文件、模拟键鼠、批量处理表格文档，适合想把重复电脑操作交给 AI 执行的开发者。它最大的特点是数据全在本机闭环，不用把工作文档往外传。但很多人在 Windows 上第一次部署时，卡住的不是安装本身，而是装完之后右上角一直显示「正在等待 Gateway 就绪」，或者干脆报 Gateway 离线，指令发出去没反应。

我试过在 Win10 和 Win11 两台机器上各部署一遍，发现报错基本集中在三类：安全软件把核心文件隔离了、安装路径带了中文或空格、Gateway 服务没起来或者端口被占。这三类问题的表现不一样，排查顺序也不一样。这篇就按「下载 → 解压 → 启动 → 验证 Gateway → 排错」的完整链路走一遍，每一步都给可复制的配置片段和验证命令，你照着做基本能一次跑通。

需要先说明的是，OpenClaw 本身是本地工具，但它的 Gateway 服务需要和模型侧通信才能下发指令。如果你想让 Gateway 稳定可用，建议提前准备好一个兼容 OpenAI 协议的接入端点。我这边用的是 TaoToken 的 API 端点，Base URL 填https://taotoken.net/api，Key 在控制台生成，模型 ID 按你实际要调的填。这样 Gateway 起来之后能直接连通模型，不会出现「服务在线但指令无响应」的中间态。

下面从环境准备开始，每一步都对应一个常见报错，你遇到哪个就翻到对应小节。

2. 部署前置：环境变量与配置文件怎么写才不报错

2.1 先确认系统版本和依赖

OpenClaw 官方包内置了 Git 和 Node.js 运行依赖，但 Windows 版本低于 Win10 1809 的话，底层 API 不完整，Gateway 启动会直接失败。先在 PowerShell 里跑一条命令确认版本：

[System.Environment]::OSVersion.Version

输出里 Major 是 10、Build 大于等于 17763 就没问题。如果 Build 低于这个数，建议先升级系统，否则后面 Gateway 初始化会卡在 60% 左右然后超时。

2.2 安装路径的硬性规范

这是报错率最高的一步。OpenClaw 的 Gateway 在启动时会用路径拼接配置文件，如果路径里有中文、空格或特殊符号，Node.js 的path模块解析会出问题，表现就是「路径非法，部署终止」。

合规路径示例：

D:\OpenClaw E:\AI\OpenClaw F:\OpenClaw_v2

违规路径示例：

D:\小龙虾 D:\Open Claw D:\软件\OpenClaw

注意OpenClaw_v2这种带下划线的是可以的，但带空格和中文的一定不行。另外尽量别装 C 盘，Gateway 运行时会写日志和缓存，占系统盘空间会影响整机响应。

2.3 环境变量与 .env 配置文件

OpenClaw 首次启动会自动生成.env文件，位置在安装目录下的config子目录。如果你要手动改，路径是：

D:\OpenClaw\config\.env

一个可用的最小配置片段如下，你可以直接复制后改 Key 和模型 ID：

# Gateway 监听端口，默认 18789，被占用时改这里 GATEWAY_PORT=18789 # 模型接入端点，TaoToken 兼容 OpenAI 协议 OPENAI_BASE_URL=https://taotoken.net/api OPENAI_API_KEY=sk-你的Key # 默认模型 ID，按你实际要调的填 DEFAULT_MODEL_ID=gpt-4o-mini # 本地数据目录，保持默认即可 DATA_DIR=./data # 日志级别，排错时改成 debug LOG_LEVEL=info

改完保存，重启 OpenClaw 客户端让配置生效。如果你用的是 Claude Code 或者 Cline 这类工具链，Base URL 和 Key 的填法是一样的，Model ID 换成对应模型即可。

2.4 安全软件的临时放行

OpenClaw 要模拟键鼠和读写文件，Windows Defender 和第三方安全软件很容易把它判定为可疑进程，直接把核心 exe 隔离掉。表现是双击启动程序后闪退，或者 Gateway 服务进程列表里找不到。

处理方式：部署阶段临时关闭实时防护，把安装目录加入白名单。具体操作是在「Windows 安全中心 → 病毒和威胁防护 → 管理设置」里关掉实时保护，然后在「排除项」里添加D:\OpenClaw整个目录。第三方安全软件同理，在隔离区恢复被拦截的文件后重新解压。

这一步做完再启动，能避开大部分「启动即闪退」的问题。

3. 可复制配置：Gateway 连通模型侧的完整参数

3.1 Gateway 的配置文件结构

OpenClaw 的 Gateway 配置分两层：一层是.env里的环境变量，一层是config/gateway.json里的服务参数。后者在首次启动时自动生成，如果没生成，你可以手动建一个：

{ "gateway": { "host": "127.0.0.1", "port": 18789, "timeout": 30000, "retry": 3 }, "model": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "gpt-4o-mini", "maxTokens": 4096 }, "log": { "level": "info", "file": "./logs/gateway.log" } }

路径是D:\OpenClaw\config\gateway.json。注意baseUrl结尾不要带/v1，TaoToken 的端点是https://taotoken.net/api，带/v1会 404。

3.2 端口占用的排查与修改

Gateway 默认监听 18789，如果这个端口被别的程序占了，Gateway 会启动失败但界面不一定报错，表现就是一直「等待就绪」。先在 PowerShell 里查一下：

netstat -ano | findstr 18789

如果有输出，说明端口被占。记下最后一列的 PID，用tasklist | findstr PID看是哪个程序。确认可以关掉就关，不能关就改.env里的GATEWAY_PORT，比如改成 18790，同时把gateway.json里的port也改成一致。

3.3 模型侧的 Key 与 Model ID 对应关系

如果你用 TaoToken 的 Coding Plan 做长期编码任务，Key 在控制台的 API Keys 页面生成。生成后填到.env的OPENAI_API_KEY和gateway.json的apiKey两处，保持一致。

Model ID 这块要注意：不同模型 ID 对应的上下文长度和计费不一样。你可以在模型对话页面先测一下目标模型能不能正常返回，再填到配置里。这样能避免「Gateway 在线但模型调用 401」的情况。

3.4 配置生效的验证方式

改完配置后，不要直接双击启动，先用命令行方式启动 Gateway，这样能看到实时日志：

cd D:\OpenClaw .\openclaw-gateway.exe --config .\config\gateway.json

如果配置有问题，控制台会直接打印错误行号和原因，比看界面日志快得多。确认能起来之后，再关掉命令行，用桌面快捷方式正常启动。

4. 验证请求：Gateway 是否真的可用

4.1 用 curl 测 Gateway 健康检查

Gateway 起来之后，先测健康检查接口。打开 PowerShell：

curl http://127.0.0.1:18789/health

正常返回应该是：

{"status":"ok","gateway":"online","uptime":12}

如果返回Connection refused，说明 Gateway 没起来，回到第 3 节查端口和配置。如果返回{"status":"error"}，看logs/gateway.log里的具体错误。

4.2 测模型侧连通性

健康检查过了，再测模型侧。Gateway 提供了一个代理接口，可以直接转发 OpenAI 格式的请求：

curl http://127.0.0.1:18789/v1/chat/completions ` -H "Content-Type: application/json" ` -d '{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}'

如果返回里有choices字段和正常内容，说明 Gateway 到模型侧的链路通了。如果返回 401，检查.env里的 Key 有没有填错或者过期。如果返回reading choices相关的解析错误，多半是模型 ID 填错了，换一个确认可用的 ID 再试。

4.3 界面侧的功能实测

命令行验证通过后，回到 OpenClaw 客户端界面，右上角应该显示「Gateway 在线」绿色标识。这时候在底部输入框下发一条测试指令：

整理 D 盘下载文件夹，按图片、文档、压缩包、安装程序分类归档，清理空目录

观察执行过程：Gateway 日志里会打印每一步的文件操作记录，界面会显示执行进度。如果指令发出去后界面一直转圈但日志没输出，说明 Gateway 收到了请求但没转发到模型侧，回到 4.2 查模型连通性。

4.4 成功结果的判定标准

一次完整的成功执行应该满足三个条件：界面显示「Gateway 在线」、命令行健康检查返回 ok、下发指令后日志有模型调用记录且文件操作实际发生。三个都满足，说明从下载到 Gateway 功能实测的链路全部打通。

5. 本篇常见报错排查：401、local proxy failed、reading choices

5.1 401 Unauthorized

报错原文：

Error: 401 Unauthorized - invalid api key

原因：.env里的OPENAI_API_KEY和gateway.json里的apiKey不一致，或者 Key 本身失效。排查步骤：先确认两处 Key 完全一致，没有多余空格；再去 TaoToken 控制台的 API Keys 页面确认这个 Key 还在有效期内。如果刚生成，等 10 秒再试，有时候有缓存延迟。

5.2 local proxy failed

报错原文：

Error: local proxy failed - connect ECONNREFUSED 127.0.0.1:18789

原因：Gateway 服务没起来，或者端口和配置不一致。排查步骤：先netstat -ano | findstr 18789确认端口有没有在监听；没有的话看gateway.json里的port和.env里的GATEWAY_PORT是否一致；都不行就用命令行方式启动看具体报错。

5.3 reading choices 解析错误

报错原文：

TypeError: Cannot read properties of undefined (reading 'choices')

原因：模型侧返回的响应格式不对，通常是 Model ID 填错，或者 Base URL 带了多余的路径。排查步骤：确认baseUrl是https://taotoken.net/api，结尾没有/v1；确认modelId是模型对话页面里验证过能正常返回的 ID；如果还不行，把LOG_LEVEL改成debug，看日志里实际请求的 URL 和响应体。

5.4 OAuth 相关报错

报错原文：

Error: OAuth token expired or invalid

原因：如果你用的是需要 OAuth 的模型接入方式，token 过期了。OpenClaw 本身不处理 OAuth 刷新，需要你在模型侧重新生成 token 后更新到配置里。如果你用的是 API Key 方式，不会遇到这个报错。

5.5 安全软件隔离导致的启动失败

报错原文：

Error: spawn openclaw-gateway.exe ENOENT

原因：openclaw-gateway.exe被安全软件隔离或删除了。排查步骤：去安全软件的隔离区恢复文件；把安装目录加入白名单；重新解压完整包再启动。如果恢复后还是 ENOENT，检查安装目录下bin子目录里有没有这个 exe。

6. 从部署到长期使用：接入方式与后续动作

Gateway 跑通之后，你可能会想把它接到更长的任务链里。OpenClaw 本身适合桌面自动化，但如果你要做长期编码或者 Agent 任务，建议把模型侧换成 Coding Plan 的接入方式，Key 和 Base URL 的填法不变，Model ID 换成 Coding Plan 支持的模型即可。这样 Gateway 转发过去的请求会走编码专用通道，长上下文任务更稳。

如果你只是想先验证模型能不能正常返回，可以在模型对话页面直接测，不用经过 Gateway。确认模型可用之后，再把 Key 和 Model ID 填到 OpenClaw 的配置里，能少走很多弯路。

接入文档里有完整的 Base URL、Key 和 Model ID 对照表，遇到配置项不确定的可以对着查。API Keys 页面用来生成和管理 Key，Coding Plan 页面用来开通长期编码通道。这三个入口配合使用，基本能覆盖从单次验证到长期运行的全部场景。

最后说一个实际踩过的坑：Gateway 的日志文件会随着运行时间增长，默认不轮转。如果你打算长期挂着，建议在gateway.json里把log.level设成warn，减少日志量，或者定期清理logs目录。这个不影响功能，但能避免磁盘被日志占满导致 Gateway 写入失败。