Windows 环境安装 openclaw 问题走一遍版本：gateway 端口与 node 配置排查

1. Windows 装完 openclaw 后 gateway 起不来先别急着重装如果你在 Windows 上装完 openclaw敲了启动命令结果浏览器打不开、终端里 gateway 一直转圈或者直接报错退出那这篇就是写给你的。openclaw 是一个本地运行的智能体网关工具它把模型调用、工具执行、会话管理这些能力收拢到一个本地服务里gateway 就是它的核心进程负责监听端口、接收请求、转发给后端模型。适合谁看适合刚在 Windows 上部署 openclaw、卡在 gateway 启动环节、又不想把整个环境推倒重来的同学。我实测下来Windows 下 gateway 启动失败九成集中在三个地方端口被占用、Node 版本不匹配、配置项没写对。这三个问题看起来像玄学其实都有明确的排查路径。下面我按「先定位、再修复、后验证」的顺序走一遍每一步都给可复制的命令和配置你照着敲就行。整个过程不需要重装 openclaw也不需要动系统环境变量以外的东西。先明确一个前提openclaw 的 gateway 默认端口是 31200但很多教程和实际配置里会改成 18789。端口这东西一旦和别的程序撞上gateway 就会启动失败或者启动了但监听不到。所以第一步永远是确认端口状态而不是反复重启。2. 动手前先把 TaoToken 的接入信息准备好openclaw 本身是个网关框架它要真正跑起来干活得有一个能调模型的入口。我这边用的是 TaoToken 的 API 接入它的地址是 https://taotoken.net/api 兼容常见的 OpenAI 风格调用方式配置起来比较直接。你需要先去控制台拿一个 API Key这个 Key 就是 openclaw 里 gateway 转发请求时用的凭证。拿 Key 的路径是打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制出来存好。注意这个 Key 只在创建时完整显示一次丢了就得重建。拿到之后openclaw 的 config.toml 里会用到它。如果你还没决定用哪个模型可以先去 https://taotoken.net/model-chat 试一下对话确认模型能正常响应再回来配 gateway这样能少走弯路。这里要提醒一句gateway 的 auth.token 和 TaoToken 的 API Key 是两个东西。前者是你本地访问 gateway 时用的门禁令牌后者是 gateway 去调模型时用的凭证。很多人把这两个搞混结果要么本地打不开要么模型调不通。下面配置里我会把两者分开写清楚。3. 可复制的 config.toml 骨架与端口检测命令先给一份能直接用的 config.toml 骨架。openclaw 的配置文件一般在用户目录下的 .openclaw 文件夹里Windows 路径类似 C:\Users\你的用户名.openclaw\config.toml。如果没有这个文件手动建一个。# openclaw gateway 基础配置 [gateway] # 监听模式本地开发用 local mode local # 监听端口默认 31200冲突时可改 18789 port 18789 # 监听地址本地回环即可 host 127.0.0.1 [gateway.auth] # 本地访问 gateway 的门禁令牌自定义 token myopenclaw123 [model] # TaoToken 的 API 入口 base_url https://taotoken.net/api # 在 TaoToken 控制台创建的 API Key api_key sk-你的TaoToken密钥 # 使用的模型名称按控制台实际可用模型填写 name gpt-4o-mini配置写完后别急着启动先做端口检测。Windows 下用 netstat 查端口占用是最稳的:: 查看 18789 端口是否被占用 netstat -ano | findstr :18789 :: 查看 31200 端口是否被占用 netstat -ano | findstr :31200如果输出里有 LISTENING 状态的行最后一列就是占用该端口的进程 PID。拿到 PID 后用 tasklist 看是哪个程序tasklist | findstr 你的PID如果发现是残留的 node.exe 占着端口直接杀掉。注意 taskkill 会杀掉所有 node 进程如果你同时跑着别的 Node 项目先确认一下再执行taskkill /f /im node.exe杀完之后再查一次端口确认干净了再启动 gateway。这一步是很多「启动失败」的真正原因——上一次 gateway 没退干净端口还占着新进程自然起不来。4. 启动 gateway 并逐步验证是否正常监听配置和端口都确认后开始启动。openclaw 的启动方式有两种一种是用全局命令一种是直接指定 dist 入口。先试全局命令openclaw gateway start --port 18789如果提示找不到命令说明 npm 全局路径没进 PATH那就用完整路径启动。你的 npm 装在哪就替换成哪的路径比如node D:\npm\global\node_modules\openclaw\dist\index.js gateway --port 18789启动后不要关终端另开一个窗口做验证。第一步看状态openclaw gateway status正常的话会显示 running 和当前监听端口。第二步用 netstat 确认端口真的在监听netstat -ano | findstr :18789看到 LISTENING 就说明 gateway 起来了。第三步用浏览器或 curl 访问curl http://127.0.0.1:18789/?tokenmyopenclaw123如果返回 JSON 或者欢迎信息说明 gateway 正常。如果返回 401说明 token 不对如果连接被拒绝说明端口没监听成功回到第 3 步查端口。还有一个容易忽略的点Node 版本。openclaw 对 Node 版本有要求太老的版本会在启动时报语法错误或者模块找不到。用下面命令查版本node -v建议用 Node 18 或 20 的 LTS 版本。如果版本太低去 Node 官网下新的 LTS 装上装完重开终端再试。版本不匹配的典型报错是SyntaxError: Unexpected token或者Cannot find module看到这类错误先查 Node 版本别急着改配置。5. 本篇常见错排查清单下面这几个错是我在 Windows 上配 openclaw 时踩过的坑按出现频率排端口占用类报错EADDRINUSE或者启动后 status 显示 failed。解决就是 netstat 查 PIDtaskkill 杀进程换端口重启。注意 31200 和 18789 都要查因为配置里可能写的是其中一个。Node 版本类报错SyntaxError或Cannot find module。解决是 node -v 确认版本低于 18 就升级。升级后记得重开终端PATH 才会刷新。配置路径类报错config not found或者 gateway 读不到 token。解决是确认 config.toml 在 C:\Users\你的用户名.openclaw\ 下文件名别写成 config.toml.txtWindows 默认隐藏扩展名很容易中招。token 不匹配类浏览器访问返回 401。解决是确认 URL 里的 token 和 config.toml 里 gateway.auth.token 完全一致大小写敏感。模型调不通类gateway 起来了但对话报错。解决是检查 model.base_url 是否为 https://taotoken.net/api api_key 是否为 TaoToken 控制台创建的 Key模型名是否在可用列表里。排查顺序建议先看端口再看 Node 版本再看配置路径最后看 token 和模型。这个顺序能覆盖绝大多数启动失败场景。6. 后续接入与长期使用建议gateway 跑通之后如果你只是偶尔用用浏览器访问 http://127.0.0.1:18789/?token你的Token 就够了。但如果你打算长期在本地做编码、跑 Agent 任务建议把 gateway 配成开机自启或者用 Coding Plan 的方式管理多个会话。TaoToken 的 Coding Plan 入口在 https://taotoken.net/coding-plan 适合需要持续调用模型的场景比每次手动起 gateway 省事。接入文档在 https://taotoken.net/doc 里面有完整的 API 参数说明和示例遇到请求格式问题可以对照查。控制台在 https://taotoken.net/console 可以看调用量和余额。如果你用的是 Claude Code 这类工具Anthropic 兼容入口在 https://taotoken.net/ClaudeCodeAnthropic 配置方式类似把 base_url 换成对应地址即可。最后说个实用技巧每次改完 config.toml先 openclaw gateway stop再 taskkill 清 node再 start。别直接重启残留进程会让你怀疑人生。端口检测命令存成一个 bat 文件双击就能查比每次手敲快得多。