目录
- [前言](#前言)
- [一、端口占用导致 Gateway 无法绑定](#一端口占用导致-gateway-无法绑定)
- [二、配置文件格式错误（YAML 五大陷阱）](#二配置文件格式错误yaml-五大陷阱)
- [三、依赖模块缺失与 Python 环境隔离](#三依赖模块缺失与-python-环境隔离)
- [四、权限问题导致启动失败](#四权限问题导致启动失败)
- [五、SSL/TLS 证书与 HTTPS 反代报错](#五ssltls-证书与-https-反代报错)
- [六、API Key 与模型服务鉴权失败](#六api-key-与模型服务鉴权失败)
- [FAQ 高频问答](#faq-高频问答)
- [结语](#结语)
前言
ZeroClaw 这类轻量级 AI 助手框架，部署门槛其实不高，但真正跑起来你会发现，服务器上”启动失败”的报错能凑一桌麻将。说白了，问题基本集中在端口、配置、依赖、权限、证书、API Key 这六类——本文就把 2026 年最常见的几条排障链路给你拆开讲清楚，每个报错都配上可直接复制的命令和验证步骤。
需要说明的是：本文以 ZeroClaw 2.x / OpenClaw 原版的 Gateway 服务（默认监听 18792 端口）为基础展开，截至 2026 年 08 月仍适用于主流社区版本。配置示例中的模型名已替换为当前主流的 GPT-5、Claude Sonnet 4.5、Gemini 2.5 Pro，老型号配置如需保留请在 providers 段单独声明。
一、端口占用导致 Gateway 无法绑定
现象描述
部署 ZeroClaw 时最常见的报错之一是 Error: listen EADDRINUSE :::18792，表示 Gateway 在尝试绑定 18792 端口时发现已被其他进程占用。同一台服务器上同时跑 OpenClaw 原版、ZeroClaw 定制版、Nginx 反向代理、调试用的第二个 ZeroClaw 实例时，端口冲突的概率几乎可以说是”必踩”。
原理分析
EADDRINUSE 错误的本质是 Linux 内核的端口复用机制。当一个进程通过 bind() 系统调用向内核申请绑定特定端口时，内核会检查该端口是否已处于 LISTEN 状态。若已被占用，内核直接返回 EADDRINUSE——系统层面没法区分”ZeroClaw 自己重复启动了”还是”被别的服务占了”，所以统一报这一个错。
可能原因详解
原因一：旧实例未正常退出
最常见场景。用 Ctrl+C 中断启动或 SSH 意外断开时，进程可能没收到 SIGTERM 信号正常退出，而是变成僵尸进程（Zombie Process）或僵死的孤儿进程。表面上没响应了，内核级别的端口占用却还没释放。
原因二：多实例部署冲突
调试阶段经常有人同时跑两个 ZeroClaw 实例（一个开发、一个生产），如果配置文件里没分开指定端口，就直接撞车。一台服务器上跑多个 AI 框架做对比测试的场景，端口管理更是必修课。
原因三：其他服务端口重叠
Nginx（默认 80/443）、Apache（默认 80/443）、OpenClaw 原版（默认 18792）、Redis（默认 6379）、MongoDB（默认 27017）若与 ZeroClaw 配了相同端口，直接绑定失败。另外不少人把 ZeroClaw 端口改成 8080、3000 这类常见 Web 端口，跟 Tomcat、Node、Grafana 撞得一塌糊涂。
解决步骤
`bash
1. 定位占用端口的进程（推荐用 ss，效率比 netstat 高）
ss -tlnp | grep 18792
备选方案：lsof（需要安装 lsof 包）
lsof -i :18792
2. 确认进程归属后终止
kill -9 <PID>
3. 若进程名包含 openclaw / zeroclaw，明确是旧实例
pkill -f zeroclaw
pkill -f openclaw
4. 强制清理残留（确保无漏网之鱼）
ps aux | grep -E ‘zeroclaw|openclaw’ | grep -v grep
5. 重新启动 ZeroClaw Gateway
zeroclaw gateway start
6. 验证端口绑定是否成功
ss -tlnp | grep 18792
`
配置层面预防
修改 ~/.openclaw/config.yml 中的端口号为未被占用的端口，建议用非标准高位端口（18792–18800 区间）：
`yaml
gateway:
port: 18793 # 更换为未被占用的端口
host: “0.0.0.0”
logLevel: “info” # 建议开详细日志便于排查
`
进阶排查技巧
netstat 配合管道过滤，可以一次性把 ZeroClaw 相关的网络连接全捞出来：
`bash
netstat -tunap | grep zeroclaw
netstat -tunap | grep 18792
`
如果想从根本上避免端口冲突，建议部署初期就制定一份端口分配表，例如：OpenClaw 原版 18792、ZeroClaw 主实例 18793、开发环境 18794、监控面板 18795……规则定下来以后基本就不会再踩这个坑了。
参考资料
- Linux
ss(8)手册页：man ss - Linux
bind(2)系统调用文档：内核对 EADDRINUSE 的定义
二、配置文件格式错误（YAML 五大陷阱）
现象描述
ZeroClaw 配置采用 YAML 格式，解析失败时会输出 Config parse error: YAML syntax error 或者直接在终端甩一段长长的 Traceback。这类错误在自部署场景里出现频率极高，主要原因是 YAML 对缩进和语法格式的要求相当严格，而很多人在编辑器里根本看不出差异。
原理分析
YAML（YAML Ain’t Markup Language）设计理念是”简洁且不易出错”，但恰恰是这种简洁性，挖了五个隐藏陷阱：
缩进敏感性问题：YAML 用空格缩进而非 Tab 字符。许多编辑器默认把 Tab 转成 Tab 字符，混用时要么报错，要么产生肉眼难以察觉的数据结构错位。
类型推断问题：YAML 会自动推断数据类型。port: 18792 解析为整数，port: "18792" 解析为字符串，配置项类型不匹配可能直接让 Gateway 启动失败。
字符编码问题：配置文件含 BOM（Byte Order Mark）或非 UTF-8 编码时，解析器读不到正确内容。BOM 字符尤其容易在 Windows 编辑器保存时悄悄塞进来。
锚点与引用陷阱：& 和 * 这类 YAML 锚点功能强大，但新手很容易在跨文件引用时把作用域搞混。
多文档分隔符：--- 既是 YAML 文档起始标志也是注释写法，一不小心就用错位置。
可能原因详解
原因一：缩进用了 Tab 而不是空格
YAML 1.2 规范明确禁止 Tab 缩进。PyYAML 等主流解析器对 Tab 支持极差，看到就直接报错。
原因二：键值对语法错误
典型坑点包括：键名后缺冒号（port 18792 写成 port 18792）、引号嵌套错误（"value: "包含冒号的值" 这种自相残杀）、注释位置错误（内联注释忘加空格）。
原因三：不可见字符污染
BOM（\xEF\xBB\xBF）、全角空格（\u3000）、从网页复制的特殊连字符（– 而不是 -）都能让解析器当场翻车。这些字符肉眼基本看不出来，必须靠工具检测——说真的，第一次被 BOM 折腾到的时候我整个人都破防了。
解决步骤
`bash
1. 直接验证 YAML 语法（最直接）
python3 -c “import yaml; yaml.safe_load(open(‘/root/.openclaw/config.yml’))”
2. 检查文件编码
file ~/.openclaw/config.yml
期望输出：”ASCII text” 或 “UTF-8 Unicode text”
若显示 “UTF-8 Unicode (with BOM)” 则需移除 BOM
3. 移除 BOM（sed 一行搞定）
sed -i ‘1s/^\xEF\xBB\xBF//’ ~/.openclaw/config.yml
4. 强制把 Tab 替换为 4 空格（推荐方案）
sed -i ‘s/\t/ /g’ ~/.openclaw/config.yml
5. 揪出残留的全角 / 非 ASCII 字符
grep -P ‘[^\x00-\x7F]’ ~/.openclaw/config.yml
6. 专业 YAML lint 工具（可选但强烈推荐）
pip install yamllint
yamllint ~/.openclaw/config.yml
`
正确格式示例（2026 版本）
`yaml
完整的 ZeroClaw 配置示例
gateway:
port: 18792
host: “0.0.0.0”
timeout: 30000
log:
level: “info”
file: “/root/.openclaw/logs/gateway.log”
plugins:
entries:
metrics-exporter:
enabled: true
config:
apiKey: “${METRICS_API_KEY}”
browser-chromium:
enabled: false
providers:
openai:
apiKey: “${OPENAI_API_KEY}”
endpoint: “https://api.openai.com/v1”
model: “gpt-5”
anthropic:
apiKey: “${ANTHROPIC_API_KEY}”
model: “claude-sonnet-4.5”
google:
apiKey: “${GOOGLE_API_KEY}”
model: “gemini-2.5-pro”
`
常见错误案例
案例一：嵌套层级错误（缩进不统一）
`yaml
错误写法
gateway:
port: 18792
host: “0.0.0.0” # 缩进不一致
正确写法
gateway:
port: 18792
host: “0.0.0.0”
`
案例二：布尔值大小写错误
`yaml
错误写法（Python 风格，YAML 不认）
plugins:
enabled: True
正确写法（YAML 1.2 标准）
plugins:
enabled: true
`
参考资料
- YAML 1.2 规范官方文档：https://yaml.org/spec/1.2.2/
- yamllint 配置说明：https://yamllint.readthedocs.io/
三、依赖模块缺失与 Python 环境隔离
现象描述
Python 环境里缺 ZeroClaw 运行所需包时，启动会报 ModuleNotFoundError: No module named 'zeroclaw'，或者 ImportError: cannot import name 'xxx' from 'zeroclaw'。这类问题在从源码部署、迁移环境、换服务器时尤为常见——基本上每次换机器都会遇到一两次。
原理分析
ZeroClaw 基于 Python 开发，依赖 Python 的模块导入机制。执行 import zeroclaw 时，解释器会按 sys.path 列表里的顺序逐个目录搜索模块（找 zeroclaw/init.py）。遍历完所有路径还没找到，就抛 ModuleNotFoundError。
依赖缺失的深层原因通常包括：虚拟环境隔离失效、pip 安装路径与 Python 解释器不匹配、依赖版本冲突覆盖等。
可能原因详解
原因一：未在虚拟环境中安装
最普遍的问题。很多人在全局 Python 环境直接 pip install zeroclaw，包被装到系统路径。当以非 root 用户或 systemd 服务方式启动时，若启动脚本用的是不同 Python 解释器，sys.path 不一样，自然就找不到。
原因二：pip 安装目录与 Python 版本不匹配
一台机器上同时有 Python 3.10、3.11、3.12 并不稀奇。用 python3.11 -m pip install 装的包，启动脚本却调 python3.12，模块当然找不到。
原因三：第三方插件依赖未同步安装
扩展插件（如 metrics-exporter、browser-chromium）依赖额外的 Python 包，这些不会在主程序安装时自动拉过来，得手动装。
解决步骤
`bash
1. 确认 Python 版本兼容性（建议 3.10+）
python3 –version
which python3
2. 创建独立虚拟环境（强烈推荐）
python3 -m venv ~/.venv/zeroclaw
source ~/.venv/zeroclaw/bin/activate
3. 在虚拟环境中安装 ZeroClaw
pip install zeroclaw –upgrade
pip install pip –upgrade # 顺手升级 pip
4. 安装插件依赖
pip install zeroclaw[monitor]
pip install zeroclaw[all] # 一次性装所有可选依赖
5. 验证安装完整性
zeroclaw –version
python3 -c “import zeroclaw; print(zeroclaw.version)”
6. 检查已安装依赖列表
pip list | grep -i zeroclaw
pip list | grep -i openclaw
`
依赖冲突解决方案
`bash
方案一：用 pip-tools 锁版本
pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt
方案二：指定版本范围安装
pip install “zeroclaw>=2.0,<3.0”
方案三：Docker 容器化部署（生产环境首选）
docker pull zeroclaw/zeroclaw:latest
docker run -d -p 18792:18792 zeroclaw/zeroclaw:latest
`
多 Python 版本共存案例
某用户服务器同时配了 Anaconda（Python 3.9）和系统 Python 3.12，用 Anaconda 环境装完 zeroclaw 后，启动脚本报找不到模块。解决方法是明确指定解释器路径：
`bash
/usr/bin/python3.9 -m pip install zeroclaw
/usr/bin/python3.9 -m zeroclaw gateway start
`
或者干脆把启动脚本的 shebang 改成具体路径，避免解释器歧义。
参考资料
- Python venv 官方文档：https://docs.python.org/3/library/venv.html
- pip-tools 项目主页：https://github.com/jazzband/pip-tools
四、权限问题导致启动失败
现象描述
ZeroClaw 启动时报 Permission denied: '/var/log/zeroclaw/gateway.log'、EACCES: permission denied, open '/root/.openclaw/config.yml'，或者 systemd 单元显示 code=exited, status=203/EXEC。这类报错 2026 年在用 systemd 管理服务的用户里特别多，本质都是”进程身份”与”文件归属”没对齐。
原理分析
Linux 一切皆文件，权限检查走的是经典的 DAC（Discretionary Access Control）模型：进程的有效 UID、GID 与文件的三组权限位（owner/group/other）比对。ZeroClaw 默认以当前用户运行，但 systemd 启动的服务通常降权到专用账户（如 zeroclaw 或 nobody），二者读写的文件归属不一致就报 EACCES。
另一个常见场景是只读文件系统（rootfs）或 SELinux / AppArmor 强制访问控制策略拒绝某些操作，即便文件权限看起来正常。
可能原因详解
原因一：日志目录归属错误
/var/log/zeroclaw/ 默认由 root 创建，但 ZeroClaw 守护进程以 zeroclaw 用户运行，无法写入。
原因二：config 文件权限过严
chmod 600 配 root owner 后，非 root 启动直接拒绝读取。
原因三：systemd 单元的 User / Group 配置错误
unit 文件里 User=zeroclaw 但 zeroclaw 用户不存在；或者 Group=nogroup 这种合法但与文件不匹配。
原因四：SELinux 上下文不匹配
CentOS / RHEL / Rocky 9+ 上 SELinux 默认开启，/root/.openclaw/ 目录如果是从其他位置 mv 过来的，SELinux context 没刷新，进程被拒绝访问。
解决步骤
`bash
1. 查看 systemd 单元当前用户
systemctl cat zeroclaw-gateway.service | grep -E “User|Group”
2. 创建专用账户（如不存在）
sudo useradd -r -s /usr/sbin/nologin zeroclaw
3. 修正文件归属
sudo chown -R zeroclaw:zeroclaw /var/lib/zeroclaw
sudo chown -R zeroclaw:zeroclaw /var/log/zeroclaw
sudo chown zeroclaw:zeroclaw /root/.openclaw/config.yml
4. 放宽或收紧权限（按需）
sudo chmod 750 /var/lib/zeroclaw
sudo chmod 640 /root/.openclaw/config.yml
5. SELinux 场景：刷新文件上下文
sudo restorecon -Rv /var/lib/zeroclaw /var/log/zeroclaw
6. AppArmor 场景：放行配置目录
sudo aa-complain /usr/bin/zeroclaw # 临时切到 complain 模式排查
sudo systemctl restart zeroclaw-gateway
7. 重启服务并验证
sudo systemctl restart zeroclaw-gateway
sudo journalctl -u zeroclaw-gateway -n 50 –no-pager
`
systemd Unit 参考写法
`ini
[Unit]
Description=ZeroClaw Gateway Service
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=zeroclaw
Group=zeroclaw
WorkingDirectory=/var/lib/zeroclaw
ExecStart=/usr/bin/python3 -m zeroclaw gateway start
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
关键安全配置
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/lib/zeroclaw /var/log/zeroclaw
[Install]
WantedBy=multi-user.target
`
避坑提示
不要为了省事把所有目录 chmod 777——这等于关掉了系统的最后一道防线，遇到挖矿木马或供应链污染时损失会非常大。正确的做法是按”最小权限原则”为每个目录单独配置 owner 和 mode。
参考资料
- systemd 单元配置手册：
man systemd.exec - SELinux 文件上下文管理：
man restorecon
五、SSL/TLS 证书与 HTTPS 反代报错
现象描述
用 Nginx / Caddy 给 ZeroClaw 做 HTTPS 反代时，常看到 SSL_CTX_use_PrivateKey_file failed、SSL: error:0900006e:PEM routines:...、certificate verify failed、或者 ZeroClaw 启动时主动调外部 HTTPS 接口报 SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]。这一组报错在 2026 年非常普遍，因为 Let’s Encrypt 证书有效期已普遍缩短，配合 ACME 自动化部署的链路稍有断点就会触发。
原理分析
HTTPS 反代的核心是两端 SSL 终结：
- 前端（Nginx → 客户端）：Nginx 用
ssl_certificate和ssl_certificate_key提供公网 HTTPS，证书过期或密钥格式错误就会报SSL_CTX_use_PrivateKey_file failed。 - 后端（Nginx → ZeroClaw Gateway）：Nginx 用
proxy_pass http://127.0.0.1:18792反代到 Gateway。这一段如果是 HTTP 通常没问题，但如果走proxy_pass https://...，ZeroClaw 自身的 CA 信任链要正确。
OpenSSL 在解析 PEM 文件时对换行、BOM、末尾换行符非常敏感——任何”看着像但实际不是”标准 PEM 的内容都会被拒绝。
可能原因详解
原因一：证书链不完整
只装了 leaf 证书（域名证书），缺 intermediate CA，客户端校验时报 unable to get local issuer certificate。
原因二：私钥与证书不匹配
重装证书时把旧私钥覆盖了，新证书跟私钥对不上。
原因三：PEM 文件含 BOM 或非标准换行
Windows 编辑器保存的 .pem 文件经常带 UTF-8 BOM，OpenSSL 解析失败。
原因四：Let’s Encrypt 自动续签失败
acme.sh / certbot 因 DNS 解析、防火墙、webroot 路径问题续签失败，证书已过期但服务没察觉。
原因五：ZeroClaw 调外部 HTTPS 接口时 CA 路径不对
Python 走 certifi 提供 CA bundle，容器化部署或最小化镜像里常常缺包。
解决步骤
`bash
1. 验证证书有效性
openssl x509 -in /etc/nginx/ssl/zeroclaw.crt -noout -dates -subject -issuer
2. 验证私钥与证书匹配（重要）
openssl x509 -in zeroclaw.crt -noout -modulus | openssl md5
openssl rsa -in zeroclaw.key -noout -modulus | openssl md5
两个 md5 一致说明配对正确
3. 验证完整证书链
openssl verify -CAfile fullchain.pem zeroclaw.crt
4. 检查 PEM 是否含 BOM
head -c 3 zeroclaw.crt | xxd
若前 3 字节是 ef bb bf，说明有 BOM
sed -i ‘1s/^\xEF\xBB\xBF//’ zeroclaw.crt
sed -i ‘1s/^\xEF\xBB\xBF//’ zeroclaw.key
5. 修正私钥权限（私钥必须 600 或 400）
chmod 600 /etc/nginx/ssl/zeroclaw.key
chown root:root /etc/nginx/ssl/zeroclaw.key
6. 测试 Nginx 配置 + 重载
sudo nginx -t
sudo systemctl reload nginx
7. ZeroClaw 端 CA bundle 修复（Python）
pip install –upgrade certifi
python3 -c “import certifi; print(certifi.where())”
如果是容器，确保 cacert 路径挂载正确
`
Nginx 反代配置示例
`nginx
server {
listen 443 ssl http2;
server_name ai.example.com;
ssl_certificate /etc/nginx/ssl/zeroclaw.crt;
ssl_certificate_key /etc/nginx/ssl/zeroclaw.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
Let’s Encrypt 续签校验
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / {
proxy_pass http://127.0.0.1:18792;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
WebSocket 支持（ZeroClaw 流式接口常用）
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection “upgrade”;
proxy_read_timeout 300s;
}
HTTP → HTTPS 强制跳转
server {
listen 80;
server_name ai.example.com;
return 301 https://$host$request_uri;
}
`
续签监控小技巧
crontab 里加一条到期前 30 天的预警：
`bash
0 9 * * * /usr/bin/openssl x509 -in /etc/nginx/ssl/zeroclaw.crt -noout -checkend 2592000 \
&& echo “OK: cert still valid 30+ days” \
|| /opt/scripts/renew-ssl.sh
`
参考资料
- Let’s Encrypt 文档：https://letsencrypt.org/docs/
- Mozilla SSL 配置生成器：https://ssl-config.mozilla.org/
六、API Key 与模型服务鉴权失败
现象描述
启动日志里冒出 Authentication failed、401 Unauthorized、403 Forbidden、429 Too Many Requests 或 Quota exceeded，ZeroClaw Gateway 无法连上外部模型服务。这是 2026 年最常见的”启动报错”之一——框架本身没问题，是上游 API 出状况或凭证配置错。
原理分析
ZeroClaw 作为多模型聚合框架，通过 providers 段统一管理各家 API。认证链路通常包含：
- 启动时从环境变量或 config 文件读取
apiKey - Gateway 首次请求时携带
Authorization: Bearer <KEY> - 上游返回 200 进入正常流程，返回 401/403 则认证失败
任一环节出错都会让 Gateway 报”启动失败”，因为 ZeroClaw 默认会在启动阶段对所有 enabled 的 provider 做一次 health check。
可能原因详解
原因一：API Key 未设置或变量名拼错
环境变量 OPENAI_API_KEY 多打一个字母就失效；.env 文件没被 source。
原因二：账户余额 / 配额耗尽
预付费账户用超额度，调用返回 429 或 Quota exceeded。
原因三：模型名与账户权限不匹配
2026 年部分模型（如 GPT-5、Claude Sonnet 4.5、Gemini 2.5 Pro）需要 Tier 2 以上账户或企业权限，开了 API 但没开模型权限。
原因四：代理 / 网络环境导致请求出不去
国内服务器调境外 API 时被防火墙或 DNS 污染拦截。
原因五：Key 已泄露被上游主动吊销
GitHub 误提交 .env 后 Key 被自动 revoke。
解决步骤
`bash
1. 检查环境变量是否生效
env | grep -iE ‘api_key|token’
echo “OPENAI_API_KEY length: ${#OPENAI_API_KEY}”
2. 单独验证 provider 联通性
python3 -c “
import os, openai
client = openai.OpenAI(api_key=os.environ[‘OPENAI_API_KEY’])
print(client.models.list().data[0].id)
“
3. 用 curl 直接打 API（排除框架干扰）
curl -sS https://api.openai.com/v1/models \
-H “Authorization: Bearer $OPENAI_API_KEY” | head -c 300
4. 检查账户配额（OpenAI 风格）
curl -sS https://api.openai.com/v1/dashboard/billing/credit_grants \
-H “Authorization: Bearer $OPENAI_API_KEY”
5. 让 ZeroClaw 跳过启动 health check（临时）
zeroclaw gateway start –skip-health-check
6. 网络问题排查
curl -v https://api.openai.com/v1/models 2>&1 | grep -E ‘TLS|connect’
ping -c 3 api.openai.com
traceroute api.openai.com
`
配置层面规范
把 API Key 放在环境变量里，不要硬编码到 config：
`yaml
providers:
openai:
apiKey: “${OPENAI_API_KEY}”
endpoint: “https://api.openai.com/v1”
model: “gpt-5”
anthropic:
apiKey: “${ANTHROPIC_API_KEY}”
model: “claude-sonnet-4.5”
google:
apiKey: “${GOOGLE_API_KEY}”
model: “gemini-2.5-pro”
启动前 source 环境变量文件
export $(cat /root/.openclaw/.env | xargs)
`
.env 文件务必 chmod 600，并加入 .gitignore。如果怀疑 Key 已经泄露，立刻到对应厂商控制台 rotate。
参考资料
- OpenAI API 鉴权文档：https://platform.openai.com/docs/api-reference/authentication
- Anthropic Console 配额管理：https://console.anthropic.com/
FAQ 高频问答
Q1：ZeroClaw 启动报 EADDRINUSE，但 ss 和 lsof 都查不到占用进程？
A：多半是 IPv6 vs IPv4 绑定冲突。ZeroClaw 默认同时绑 0.0.0.0 和 ::，检查 ss -tlnp6 | grep 18792。另一种可能是容器内进程被宿主机 namespace 隔离看不到，需要进容器内部查。
Q2：YAML 配置 python3 -c yaml.safe_load 能过，但 ZeroClaw 还是报语法错误？
A：检查是否有 & 锚点引用、--- 多文档分隔符、!!python/object/apply 这类 PyYAML 特有的构造。ZeroClaw 默认用 safe_load，但部分写法仍会被拒。改用 yamllint -d "{extends: default, rules: {line-length: disable}}" 看具体提示。
Q3：pip install 成功但 import zeroclaw 报 ModuleNotFoundError，怎么排查？
A：八成是解释器不一致。which python3 和 which pip 分别看一下指向。如果系统装了 python3.10 和 python3.12，pip install 默认装到 3.10，但 systemd 调的是 3.12。统一用 python3 -m pip install 强制对齐。
Q4：systemd 启动 ZeroClaw 一直 code=exited, status=203/EXEC，怎么破？
A：status=203 是经典的 ExecStart 路径错误或解释器缺失。systemctl cat zeroclaw-gateway.service 看 ExecStart 的实际命令，手动复制粘贴跑一遍。常见坑：Python 路径不对、virtualenv activate 脚本缺失、WorkingDirectory 不存在。
Q5：Nginx 反代后 ZeroClaw 接口 504 Gateway Timeout？
A：多半是 proxy_read_timeout 太短，ZeroClaw 流式生成耗时超过默认 60s。把 timeout 调到 300s，并确认后端 Gateway 没因 OOM 被 kill。另外检查 ZeroClaw 日志里有没有 upstream timed out。
Q6：YAML 文件明明是 UTF-8，为什么 file 命令显示 UTF-8 Unicode (with BOM)？
A：被 Windows 编辑器或某些 IDE 写入时加了 BOM，Python 解析器看不到文件起始位置。sed -i '1s/^\xEF\xBB\xBF//' file.yml 一行解决，完事再 file 验证一次。
Q7：ZeroClaw 启动后立刻退出，systemd 状态显示 status=2？
A：通常是配置文件被改了但缺关键字段（gateway.port、providers.*.apiKey），或者环境变量没注入。先前台运行 zeroclaw gateway start --foreground 看完整报错。
Q8：能不能在同一台服务器同时跑 ZeroClaw 和 OpenClaw 原版？
A：完全可以，端口分开就行。OpenClaw 原版用 18792，ZeroClaw 用 18793-18800 区间。注意 API Key 和数据库路径也要分开，避免数据互相覆盖。
Q9：ZeroClaw 配置里 model 字段写 gpt-4 还是 gpt-5 合适？
A：截至 2026 年 08 月，主流模型已是 GPT-5、Claude Sonnet 4.5、Gemini 2.5 Pro。建议优先写最新版本，旧型号仅在特定兼容场景保留。
Q10：Docker 部署 ZeroClaw 还需要装虚拟环境吗？
A：不需要。Docker 镜像本身就是隔离环境，pip install 直接生效。但建议用 python:3.12-slim 之类的基础镜像，并在 Dockerfile 里显式 pip install --no-cache-dir，减小镜像体积。
结语
老实讲，ZeroClaw 这类轻量框架的”启动失败”问题，90% 都集中在端口、配置、依赖、权限、证书、API Key 这六类。掌握本文的排障链路后，大多数报错基本 5–10 分钟内可以定位——剩下的 10% 是冷门 edge case，需要结合具体日志和官方 Issue 进一步分析。
部署过程中养成几个好习惯：端口规划提前写文档、配置改动一律走环境变量、依赖用虚拟环境隔离、systemd 单元按最小权限配置、证书接入 ACME 自动续签、API Key 用 .env 文件管理并加入 .gitignore。这些动作做扎实了，启动失败基本告别。
如果本文里某个报错没覆盖到，或者你踩到了新的坑，欢迎在评论区贴完整日志——一般带上 ZeroClaw 版本、zeroclaw --version 输出、journalctl -u zeroclaw-gateway -n 100 结果，社区里基本都能复现定位。