八、常见问题与故障排除

8.1 快速诊断入口

如果你想快速走一遍"解决问题"流程，请从这里开始：

openclaw doctor 是自动诊断和修复工具：

openclaw doctor

它会：

# 检查 Node 是否已安装
node -v
 
# 检查全局软件包安装位置
npm prefix -g
 
# 检查 PATH
echo "$PATH"

解决方法：将 $(npm prefix -g)/bin 添加到 PATH：

export PATH="$(npm prefix -g)/bin:$PATH"

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

错误信息	原因	解决方法
`refusing to bind gateway ... without auth`	非 loopback 绑定且没有认证	配置 `gateway.auth.token` 或 `gateway.auth.password`
`EADDRINUSE`	端口被占用	更换端口或 `openclaw gateway --force`
`Gateway start blocked: set gateway.mode=local`	配置被设为远程模式	设置 `gateway.mode: "local"`
`unauthorized during connect`	身份验证不匹配	检查 token/password 配置

# 基本状态
openclaw gateway status
 
# 深度检查
openclaw gateway status --deep
 
# JSON 格式
openclaw gateway status --json
 
# 健康检查
openclaw health

# 强制终止端口上的监听器
openclaw gateway --force
 
# 或更换端口
openclaw gateway --port 19001

# 检查渠道状态
openclaw channels status --probe
 
# 查看日志
openclaw logs --follow

# 实时查看日志
openclaw logs --follow
 
# 查看最近日志
openclaw logs

OpenClaw 在哪里加载环境变量以及优先级：

openclaw gateway --verbose

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

默认值包括隔离的 state/config 和基础 Gateway 端口 19001。

适合开发者和高级用户，希望拥有个人 AI 助手且不想放弃数据控制。

可以。支持 VPS、Docker、Fly.io、Hetzner、GCP、Azure、Railway、Render 等。

可以。OpenClaw 会按聊天进行路由。

完全自托管，数据在你的机器上。Gateway 认证和允许列表提供安全保障。

# 检查节点状态
openclaw nodes status
 
# 查看待配对设备
openclaw devices list

# 查看节点权限
openclaw nodes describe --node <id>
 
# 添加 allowlist
openclaw approvals allowlist add --node <id> "/usr/bin/uname"