Skip to content
OpenClaw 书稿预览

第4章 10分钟排坑：当事情不顺利时

🎯 本章目标：学完这章，你能独立解决安装和初装阶段最常见的问题

⏱️ 预计时间：10分钟

📋 前置要求：已完成第3章（安装）

本章你将学会什么

Section titled “本章你将学会什么”
  • 用系统化方法排查问题
  • 解决”command not found”错误
  • 解决端口被占用问题
  • 解决401/403 API错误
  • 解决Web UI无响应问题
  • Windows用户的特殊注意事项

4.1 排障方法论：别慌，按步骤来

Section titled “4.1 排障方法论：别慌，按步骤来”

遇到问题时，很多人第一反应是”我哪里做错了”。

淡定。排障本身就是学习。

OpenClaw提供了几个诊断工具，按这个顺序排查：

1. openclaw status    → 看整体状态
2. openclaw doctor    → 自动诊断常见问题
3. openclaw logs      → 查看详细日志

记住这个口诀：status 看全局，doctor 跑体检，logs 看证据。

4.2 问题一：“command not found”

Section titled “4.2 问题一：“command not found””

4.2.1 一眼症状

Section titled “4.2.1 一眼症状”
Terminal window
$ openclaw --version
zsh: command not found: openclaw

或

Terminal window
$ openclaw --version
bash: openclaw: command not found

4.2.2 可能原因

Section titled “4.2.2 可能原因”
  1. npm全局路径未加入系统PATH
  2. 安装未完成
  3. 终端需要重启

4.2.3 解决动作

Section titled “4.2.3 解决动作”

步骤1：重启终端

最简单的方法，先试试关闭终端重新打开。

步骤2：检查npm全局路径

Terminal window
npm prefix -g

输出类似：

/usr/local

然后检查这个路径的bin子目录是否在PATH中：

Terminal window
echo $PATH | grep $(npm prefix -g)

如果没有输出，说明路径没加进去。

步骤3：手动添加PATH（macOS/Linux）

编辑你的shell配置文件：

Terminal window
# 如果是zsh（macOS默认）
nano ~/.zshrc


# 如果是bash
nano ~/.bashrc

在文件末尾添加：

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

保存后，重新加载配置：

Terminal window
source ~/.zshrc  # 或 source ~/.bashrc

步骤4：验证

Terminal window
openclaw --version

应该显示版本号了。

4.3 问题二：端口被占用

Section titled “4.3 问题二：端口被占用”

4.3.1 一眼症状

Section titled “4.3.1 一眼症状”
✗ Gateway failed to start
Error: Port 18789 is already in use

4.3.2 可能原因

Section titled “4.3.2 可能原因”
  1. 之前启动的Gateway还在运行
  2. 其他程序占用了18789端口

4.3.3 解决动作

Section titled “4.3.3 解决动作”

方案A：杀掉占用进程

Terminal window
# 查找占用18789的进程
lsof -i :18789


# 输出示例：
# COMMAND  PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# node    1234 dracohu   21u  IPv6 ...


# 杀掉进程（把1234换成实际的PID）
kill 1234


# 如果杀不掉，强制杀
kill -9 1234

方案B：更换端口

Terminal window
# 用其他端口启动
openclaw gateway start --port 18790

然后访问：http://127.0.0.1:18790

方案C：检查是否已有Gateway在运行

Terminal window
openclaw status

如果显示Gateway已经在运行，直接访问即可，不需要再启动。

4.4 问题三：401/403错误

Section titled “4.4 问题三：401/403错误”

4.4.1 一眼症状

Section titled “4.4.1 一眼症状”

Web UI里发送消息后，显示错误：

Error: 401 Unauthorized

或

Error: 403 Forbidden

4.4.2 可能原因

Section titled “4.4.2 可能原因”
错误码含义常见原因
401未授权API Key错误、Key已失效
403禁止访问额度用完、账号被限制、IP被限制

4.4.3 解决动作

Section titled “4.4.3 解决动作”

步骤1：检查API Key

Terminal window
openclaw config get

确认显示的Key和你申请的一致。

步骤2：验证Key有效性

去对应的Coding Plan控制台，检查：

  • Key是否被删除/重置
  • 账号状态是否正常
  • 余额/额度是否充足

步骤3：检查网络

Terminal window
# 测试能否访问KIMI API（以KIMI为例）
curl https://api.kimi.com/v1/models \
  -H "Authorization: Bearer 你的API Key"

如果返回401，说明Key确实有问题。

步骤4：重新配置

Terminal window
# 重新设置模型
openclaw models set


# 或者重新运行向导
openclaw onboard

4.5 问题四：页面打开但不出回复

Section titled “4.5 问题四：页面打开但不出回复”

4.5.1 一眼症状

Section titled “4.5.1 一眼症状”
  • Web UI能打开
  • 能输入消息
  • 发送后一直”正在输入”，没有回复
  • 或者提示连接错误

4.5.2 可能原因

Section titled “4.5.2 可能原因”
  1. 模型配置错误
  2. 网络代理问题
  3. Gateway异常

4.5.3 解决动作

Section titled “4.5.3 解决动作”

步骤1：检查Gateway状态

Terminal window
openclaw status

应该显示：

Gateway: running

步骤2：查看日志

Terminal window
openclaw logs

看最新的错误信息。

步骤3：检查模型连接

Terminal window
openclaw doctor

这个命令会自动检测常见问题。

步骤4：检查网络代理

如果你使用了代理软件（Clash、V2Ray等），可能导致OpenClaw无法直连国内API。

macOS/Linux设置代理白名单：

Terminal window
# 对特定地址不走代理
export NO_PROXY="127.0.0.1,localhost"

步骤5：重启Gateway

Terminal window
openclaw gateway stop
openclaw gateway start

4.6 问题五：Windows用户的特殊注意事项

Section titled “4.6 问题五：Windows用户的特殊注意事项”

4.6.1 推荐方案：使用WSL2

Section titled “4.6.1 推荐方案：使用WSL2”

Windows的终端环境比较复杂，各种权限、路径问题层出不穷。

官方推荐：在WSL2（Windows Subsystem for Linux）中运行OpenClaw。

WSL2安装步骤：

  1. 打开PowerShell（管理员），运行：
Terminal window
wsl --install
  1. 重启电脑
  2. 设置Linux用户名和密码
  3. 在WSL2中按照本书的Linux步骤操作

WSL2的好处：

  • 和macOS/Linux一致的体验
  • 避免Windows特有的路径问题
  • 更好的权限管理

4.6.2 如果一定要在Windows原生环境运行

Section titled “4.6.2 如果一定要在Windows原生环境运行”

注意事项：

  1. 使用PowerShell或CMD，不要用Git Bash
  2. 以管理员身份运行终端
  3. 检查Windows防火墙，确保18789端口开放

检查防火墙：

Terminal window
# 以管理员身份运行PowerShell
netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=TCP localport=18789

4.7 排障决策树

Section titled “4.7 排障决策树”

遇到问题时，按这个流程排查：

遇到问题
    ↓
运行 openclaw status
    ↓
Gateway运行正常？
    ↓ 否                    ↓ 是
检查安装    →  command not found？→  修复PATH
    ↓ 是
检查端口占用 →  换端口或杀进程
    ↓
Gateway运行正常
    ↓
Web UI能打开？
    ↓ 否                    ↓ 是
检查防火墙    →   检查浏览器控制台
    ↓
能发消息但无回复？
    ↓ 是
运行 openclaw doctor
    ↓
检查API Key
    ↓
检查网络/代理
    ↓
查看 openclaw logs

4.8 什么时候该求助

Section titled “4.8 什么时候该求助”

如果你已经：

  • 按本章步骤排查过
  • 试过重启Gateway
  • 查看过日志但看不懂

可以去这些地方求助：

  1. OpenClaw Discord社区：https://discord.gg/openclaw
  2. GitHub Issues：https://github.com/openclaw/openclaw/issues
  3. 官方文档：https://docs.openclaw.ai

提问时请提供：

  • 操作系统版本
  • OpenClaw版本（openclaw --version）
  • 完整的错误信息
  • 你尝试过的解决方法

本章小结

Section titled “本章小结”

记住这些排障要点：

  1. status → doctor → logs 三步诊断法
  2. command not found → 检查PATH，重启终端
  3. 端口占用 → 杀进程或换端口
  4. 401/403 → 检查API Key和额度
  5. 无回复 → 检查网络、代理、模型配置
  6. Windows用户 → 推荐WSL2

排障是编程的一部分，每一次解决问题都是进步。

动手试试

Section titled “动手试试”
  1. 运行openclaw doctor，看看有没有潜在问题
  2. 查看openclaw logs，熟悉日志格式
  3. 故意输错API Key，观察错误信息，然后修复
  4. 如果一切正常，恭喜你！准备进入第5章，接入飞书！