一个中文用户名引发的血案：Windows 编码问题排查实录

一句话总结

Windows 计划任务用 GBK 编码读 UTF-8 文件，中文用户名变成乱码，Node.js 找不到模块，网关启动失败。

现象：网关死活连不上

我在安装 OpenClaw 的 Gateway 服务时，安装向导提示：

◇  Gateway service installed.
Health check failed: connect ECONNREFUSED 127.0.0.1:18789

端口 18789 连接被拒绝。典型的“服务没起来”。

安装程序自动创建了一个 Windows 计划任务 OpenClaw Gateway，用它在后台拉起 Node.js 网关进程。任务创建成功了，但进程显然没跑起来。

新手第一反应：是不是配置文件写错了？是不是防火墙拦了？是不是端口冲突了？

排查第一层：配置文件、防火墙、端口

先看配置文件 openclaw.json：

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "mode": "local"
  }
}

端口 18789，绑定 127.0.0.1，认证 token 也配了。配置没问题。

再看端口占用：

> netstat -ano | findstr 18789
（空）

没人监听。防火墙是 loopback 通信，根本不过防火墙。排除。

排查第二层：手动 vs 计划任务

试试手动跑：

> node "C:\Users\一生只爱歪脖子树\...\openclaw\dist\index.js" gateway --port 18789

[gateway] loading configuration…
[gateway] resolving authentication…
[gateway] starting...

三秒就起来了，端口监听正常，健康检查 200 OK。

手动启动正常，计划任务启动失败 — 问题锁定在计划任务的执行环境上。

看计划任务状态：

TaskName     : OpenClaw Gateway
State        : Ready
LastTaskResult: 1          ← 退出码 1，失败了

排查第三层：直接跑脚本看报错

计划任务实际执行的是一个 .cmd 脚本：

@echo off
set "OPENCLAW_GATEWAY_PORT=18789"
"C:\Program Files\nodejs\node.exe" ^
  "C:\Users\一生只爱歪脖子树\AppData\Roaming\npm\node_modules\openclaw\dist\index.js" ^
  gateway --port 18789

在 cmd 窗口里直接跑这个脚本：

Error: Cannot find module 'C:\Users\涓€鐢熷彧鐖辨瓑鑴栧瓙鏍慭AppData\...'

乱码！ 中文用户名 一生只爱歪脖子树 变成了 涓€鐢熷彧鐖辨瓑鑴栧瓙鏍。

根因：Windows 编码机制的经典坑

这背后是 Windows 两层编码体系的老问题：

第一层：文件编码

gateway.cmd 文件本身是 UTF-8 编码的。OpenClaw 安装程序写文件时用 UTF-8，中文字符原样保存。

第二层：系统代码页（System Locale / ANSI Code Page）

Windows 有一个“非 Unicode 程序的语言”设置。中文 Windows 默认是 GBK（CP936）。

当 Windows 计划任务或服务进程（尤其是以 SYSTEM 账户运行时）读取一个 .cmd 文件，cmd.exe 使用系统的 ANSI 代码页来解释文件内容。

UTF-8 编码的 一生只爱歪脖子树 字节序列，被 GBK 解码器错误解释，就变成了 涓€鐢熷彧鐖辨瓑鑴栧瓙鏍。

具体机制：

UTF-8 字节:    E4 B8 80 E7 94 9F ...
GBK 解码后:    涓   €   鐢   熷   ...
Node 解析:     路径不存在 → 报错退出

这不是 bug，是 Windows 的历史设计。Win32 API 有两套：CreateFileA（ANSI）和 CreateFileW（Unicode）。很多底层组件默认走 ANSI 路径。

修复：一行改动

Before:

"C:\Program Files\nodejs\node.exe" C:\Users\一生只爱歪脖子树\AppData\Roaming\npm\node_modules\openclaw\dist\index.js gateway --port 18789

After:

openclaw gateway --port 18789

openclaw 是 npm 全局安装的命令，在 PATH 里。npm 安装时会把可执行脚本写到 %APPDATA%\npm\（也是中文路径），但 npm 自己处理了路径解析，不需要在 .cmd 文件里硬编码绝对路径。

任何能避免在启动脚本中写死含非 ASCII 字符的绝对路径的方案都管用。

复盘：为什么这个问题有普遍意义

1. 症状与根因脱节

你看到的是 ECONNREFUSED（网络连接被拒），但根因是编码问题。中间隔了四层：网络层 → 进程层 → 脚本层 → 编码层。

2. 环境差异难以复现

手动在终端跑：你的终端是 UTF-8，正常
计划任务跑：SYSTEM 账户 + GBK 代码页，乱码
同样的脚本，不同上下文，完全不同的行为

3. 中文开发者高频踩坑

全球开发者中，用非 ASCII 字符（中文、日文、韩文、带重音的拉丁文）做用户名 / 路径名的人占比很大。但大多数开源工具的开发者和测试者用的是纯 ASCII 环境，导致这类 bug 很容易漏到用户侧。

4. 一个启发式的排查思路

当你遇到“某种启动方式失败但手动启动成功”的问题时：

先比环境变量（set 输出）
再看运行账户（whoami）
最后怀疑一下编码（chcp 看代码页）

修复后的完整状态

检查项	状态
端口 18789 监听	✅ LISTENING
健康检查 /health	✅ 200 OK
计划任务启动	✅ 正常运行
配置文件	✅ 无需修改

如果重来一次，5 分钟怎么定位？

1. netstat -ano | findstr 18789     → 端口没监听 → 进程没起
2. 手动跑 gateway.cmd               → 看报错信息
3. 报错里有乱码                     → 编码问题锁定
4. 改脚本，用 PATH 命令代替写死路径 → 修好

关键是第二步：手动跑一次启动脚本，直接看标准错误输出。很多时候，第一步就破案。

2026-05-20 · 案例复盘