Skip to content
今天更新

故障排查

本页汇总了 OpenClaw 使用过程中的常见问题和解决方案,内容基于社区高频反馈整理。

诊断工具速查

遇到问题时,先运行以下命令收集信息:

bash
openclaw status          # 查看运行状态
openclaw status --deep   # 深度健康检查
openclaw doctor          # 系统诊断和修复建议
openclaw logs --follow   # 实时查看日志
openclaw gateway restart # 重启网关

openclaw doctor 是你的第一选择

openclaw doctor 是内置的自动诊断工具,能检测大部分常见问题并给出修复建议。遇到任何异常,优先运行它。

常见问题

1. Tools Profile Bug(v3.7 之前版本)

现象:OpenClaw 只给出建议文字,但不会实际执行任何操作(如不会创建文件、不会运行命令)。

原因:v3.7 之前的版本默认 tools.profilesuggest,只提供建议而不执行。

解决方案

bash
# 将 tools.profile 设置为 full,允许完整工具调用
openclaw config set tools.profile full

# 重启网关使配置生效
openclaw gateway restart

升级到 v3.7+ 后不再需要此操作

v3.7 及以后版本已将默认值改为 full。如果你是新安装用户,通常不会遇到此问题。

2. 网关未运行

现象:发送消息无响应,Web 控制台无法打开。

排查步骤

bash
# 检查网关状态
openclaw status

# 如果显示 stopped,重启网关
openclaw gateway restart

如果重启后仍然失败,查看日志获取详细错误:

bash
openclaw logs --follow

常见原因:

  • 端口被其他进程占用
  • Node.js 版本不满足要求
  • 配置文件损坏

3. 模型 API 连接失败

现象:发送消息后返回错误提示,如 API connection failed401 Unauthorized

排查步骤

bash
# 深度健康检查,会测试 API 连通性
openclaw status --deep

逐项检查

  • API Key 是否正确openclaw config get models 查看当前配置,确认 Key 未过期
  • Base URL 是否正确:如果使用自定义 API 端点,确认 URL 格式正确且可访问
  • 网络是否通畅:确认能访问模型提供商的 API 地址(国内用户注意代理配置)
bash
# 重新设置 API Key
openclaw config set models.anthropic.apiKey sk-xxx

# 设置自定义 Base URL(如使用代理)
openclaw config set models.anthropic.baseUrl https://your-proxy.com/v1

4. 频道无响应

现象:消息发出去了,但 AI 没有回复。

排查步骤

bash
# 检查所有频道的连接状态
openclaw channels status

常见原因与解决

  • Token 格式错误:确认 Token 没有多余的空格或换行符
  • Token 已失效:重新生成并配置 Token
  • 网关未运行:先确认网关状态正常
bash
# 重新配置频道 Token
openclaw channels login <channel-name>

# 重启网关
openclaw gateway restart

5. Node.js 版本问题

现象:安装失败或运行时报语法错误。

要求:OpenClaw 需要 Node.js 22 或更高版本。

bash
# 检查当前版本
node --version

如果版本低于 22,请升级:

bash
# 使用 nvm 安装最新 LTS 版本
nvm install 22
nvm use 22

# 或直接从官网下载:https://nodejs.org/

不要使用 Node.js 18 或更低版本

OpenClaw 使用了大量 Node.js 22 的新特性,低版本无法运行。

6. npm install 失败(国内网络问题)

现象npm install -g openclaw 卡住或报网络错误。

解决方案:切换为国内镜像源。

bash
# 设置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 然后重新安装
npm install -g openclaw@latest

临时使用镜像

如果不想全局修改,可以单次指定:

bash
npm install -g openclaw@latest --registry https://registry.npmmirror.com

7. Skills 不工作

现象:调用技能时无反应或报错 skill not found

排查步骤

bash
# 检查 tools.profile 是否为 full
openclaw config get tools.profile

# 查看已启用的技能列表
openclaw skills list

解决

bash
# 确保 tools.profile 设置为 full
openclaw config set tools.profile full

# 如果技能未启用,手动启用
openclaw skills enable <skill-name>

# 重启网关
openclaw gateway restart

8. Token 消耗过高

现象:使用一段时间后,API 费用明显增加。

原因:随着对话进行,上下文(Context)不断增长,每次请求发送的 Token 数量越来越多。

优化建议

  • 使用更便宜的模型:日常对话可以切换到成本较低的模型
  • 使用 Coding Plan 模式:先让模型制定计划再执行,减少反复试错的 Token 消耗
  • 及时清理上下文:长对话可以通过新开会话来重置上下文
  • 设置 Token 预算:通过配置限制单次对话的最大 Token 数
bash
# 切换模型
openclaw config set models.default <cheaper-model>

9. Cron 定时任务未执行

现象:设置了定时任务但没有按时运行。

排查步骤

bash
# 查看已注册的 Cron 任务
openclaw cron list

# 确认网关正在运行(Cron 依赖网关)
openclaw status

常见原因

  • 网关未运行:Cron 任务由网关调度,网关停止后任务不会执行
  • --channel 格式错误:确认频道名称拼写正确
  • 时区问题:确认 Cron 表达式使用的时区与预期一致
bash
# 重启网关确保 Cron 调度器运行
openclaw gateway restart

10. 使用 openclaw doctor 全面诊断

当以上方法都无法定位问题时,运行完整诊断:

bash
openclaw doctor

openclaw doctor 会自动检测:

  • Node.js 版本是否满足要求
  • 网关是否正常运行
  • API Key 是否有效
  • 频道连接是否正常
  • 配置文件是否有语法错误
  • 磁盘空间和端口占用情况

根据诊断结果,它会给出具体的修复建议和命令,按提示操作即可。

11. API 限流(429 Too Many Requests)

现象:频繁调用后返回 429 错误。

解决方案

  • 降低调用频率,减少活跃技能数量
  • 配置 Fallback 模型,自动切换到其他供应商
  • 联系模型供应商提升限额
json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallback": ["openrouter/google/gemini-flash-1.5"]
      }
    }
  }
}

12. 记忆丢失 / 上下文超出

现象:Agent 忘记之前的对话内容,或提示上下文超出限制。

原因:对话过长,超出模型的上下文窗口(Context Window)。

解决

  • 开启新会话重置上下文
  • 将重要信息写入 MEMORY.md 持久保存
  • 使用支持更长上下文的模型(如 Moonshot 128K)

13. Windows PowerShell 执行策略

现象:Windows 下安装时报 ExecutionPolicy 错误。

解决:以管理员身份运行 PowerShell:

powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

50 条高频踩坑清单

来源

本清单整理自《OpenClaw 蓝皮书》第十六章,涵盖社区最高频的 50 个踩坑场景。与上方"常见问题"已收录的条目(如 API Key、端口占用、Token 消耗、上下文丢失、API 限流等)不再重复列出,请交叉参考。

16.1 配置类踩坑(#1-#15)

#1 SOUL.md 太长导致 token 浪费

  • 问题:SOUL.md 写了 2000 字,每次调用浪费大量 token
  • 解决:SOUL.md 控制在 300 字以内,删除所有可推断的废话
  • 节省:每月可减少 30-50% 的成本

#3 openclaw.json 格式错误

  • 问题:JSON 配置文件有语法错误导致启动失败
  • 解决:用工具验证 JSON 格式
bash
# 验证JSON格式
python -m json.tool openclaw.json
# 或
cat openclaw.json | python3 -c "import json,sys; json.load(sys.stdin); print('JSON OK')"

#4 端口被占用

  • 问题:启动时报端口冲突
  • 解决:查找并释放占用端口的进程
bash
# 查找占用8080端口的进程
lsof -i :8080  # Mac/Linux
netstat -ano | findstr :8080  # Windows
# 杀死进程
kill -9 <PID>
# 或修改配置使用其他端口

#5 Docker 内无法访问宿主机服务

  • 问题:容器内使用 localhost:5432 无法连接宿主机 PostgreSQL
  • 解决:使用正确的宿主机地址
yaml
# 正确做法
environment:
  - DATABASE_URL=postgresql://user:[email protected]:5432/db
# Windows/Mac 用 host.docker.internal
# Linux 用 172.17.0.1 (docker0网桥IP)

#6 中文乱码问题

  • 问题:Linux 服务器上输出中文乱码
  • 解决:设置正确的 locale
bash
# Linux服务器常见问题
export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8
# Docker镜像需要安装中文locale
RUN apt-get install -y locales && \
    locale-gen zh_CN.UTF-8

#7 AGENTS.md 配置不生效

  • 问题:写好了 AGENTS.md 但 Agent 行为没有变化
  • 解决:逐项检查
    • 文件名是否完全正确:AGENTS.md(大写)
    • 是否放在项目根目录(不是子目录)
    • 格式是否符合规范
    • 重启 OpenClaw 后重新加载

#8 记忆文件越来越大导致变慢

  • 问题:长期使用后记忆文件膨胀,响应变慢
  • 解决:配置记忆文件管理
yaml
// openclaw.json - 记忆文件管理
memory:
  maxSize: 50000  # 最多5万字
  compressionEnabled: true
  cleanupInterval: "weekly"
  archiveOldMemories: true

#9 Webhook URL 配置错误

  • 问题:Webhook 回调不生效
  • 解决:先测试 URL 是否可达
bash
# 测试Webhook是否可达
curl -X POST your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{"test": "hello"}'
# 应该收到200响应

#10 模型版本 deprecated

  • 问题:报错 model_not_found
  • 解决:检查是否在使用已下线的模型版本
bash
# 常见错误:model_not_found
# 检查是否在使用已下线的模型版本
# 旧版:claude-3-sonnet-20240229 (已下线)
# 新版:claude-3-5-sonnet-20241022
# 建议始终订阅官方changelog邮件

#11 超过模型最大 token 限制

  • 问题:报错 max_tokens exceeds model limit
  • 解决:设置安全的 maxTokens 值
json
{
  "llm": {
    "maxTokens": 4096  // 安全值,适用所有Claude模型
  }
}

各模型 maxTokens 参考

  • Haiku 最大:8192 tokens
  • Sonnet 最大:8192 tokens
  • Opus 最大:4096 tokens

#12 temperature 设置不当

  • 问题:Agent 输出不稳定或过于死板
  • 解决:根据场景选择合适的 temperature
    • 0:完全确定性,适合数据处理/工具调用
    • 0.3:推荐的平衡值,适合大多数场景
    • 0.7:创意写作
    • 1.0:高随机性,通常不推荐在 Agent 中使用

#13 同时运行多个 OpenClaw 实例

  • 问题:多个实例争抢同一个资源文件
  • 解决:检查并清理重复进程
bash
# 检查是否有重复运行
ps aux | grep openclaw
# 如有多个,保留一个,杀死其他

#14 云服务器防火墙未开放端口

  • 问题:部署到云服务器后外部无法访问
  • 解决:在安全组和服务器防火墙中开放端口
bash
# 阿里云/腾讯云需要在安全组添加规则
# 开放 8080 端口(或你配置的端口)
# 入站规则:TCP,端口8080,来源0.0.0.0/0
# 同时服务器本身也需要开放
ufw allow 8080  # Ubuntu
firewall-cmd --add-port=8080/tcp --permanent  # CentOS

#15 SSL 证书问题

  • 问题:报错 SSL: CERTIFICATE_VERIFY_FAILED
  • 解决:安装证书或临时跳过验证
bash
# 方案一:安装证书
pip install certifi
# 方案二(不推荐,仅开发环境):跳过验证
# 在openclaw.json中设置 "sslVerify": false

16.2 运行时踩坑(#16-#30)

#16 Agent 陷入无限循环

  • 问题:Agent 不停调用同一个工具,不返回结果
  • 原因:工具返回结果不符合预期,Agent 重试
  • 解决
    1. 设置 maxIterations: 20(最多循环 20 次)
    2. 工具失败时返回明确的错误信息
    3. SOUL.md 中写明"如果工具调用失败 3 次,终止任务并报告"

#17 工具调用参数格式错误

  • 问题:模型传入字符串,但工具期望数字
  • 解决:在工具定义中明确类型和描述
json
{
  "name": "search_products",
  "parameters": {
    "price_max": {
      "type": "number",
      "description": "最高价格,单位元,请传入数字如:100"
    }
  }
}

#19 并发请求导致资源竞争

  • 问题:多用户同时使用时出现异常
  • 解决:配置并发控制
yaml
// openclaw.json - 并发控制
concurrency:
  maxConcurrentUsers: 10     # 最多10个并发用户
  maxConcurrentTools: 3      # 每用户最多3个并发工具调用
  queueTimeout: 30           # 等待超时30秒
  rateLimit:
    windowMs: 60000
    maxRequests: 100

#20 Telegram Bot 消息重复发送

  • 问题:Telegram Webhook 超时,重复发送 update
  • 解决:记录已处理的 update_id,跳过重复消息
python
processed_updates = set()

def handle_update(update):
    if update.update_id in processed_updates:
        return  # 重复,跳过
    processed_updates.add(update.update_id)
    # 处理消息...

#21 Agent 任务超时

  • 问题:长时间运行的任务被强制终止
  • 解决:配置合理的超时时间
json
{
  "taskTimeout": {
    "default": 60,             // 默认60秒超时
    "longRunning": 300,        // 长任务300秒
    "onTimeout": "graceful_stop",  // 优雅停止
    "saveProgress": true       // 超时前保存进度
  }
}

#22 工具返回过多数据

  • 问题:搜索返回 1000 条结果,塞满上下文
  • 解决
    1. 工具内部限制返回数量(maxResults: 5
    2. 关键信息提取后再返回
    3. 分页处理,不要一次返回所有

#23 外部 API 限流

  • 问题:调用第三方 API 时被限流
  • 解决:在工具代码中添加重试机制(指数退避)
python
import time
from functools import wraps

def with_retry(max_retries=3, delay=2):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except RateLimitError:
                    if attempt < max_retries - 1:
                        time.sleep(delay * (2 ** attempt))  # 指数退避
                    else:
                        raise
        return wrapper
    return decorator

#24 数据库连接池耗尽

  • 问题:高并发时数据库连接耗尽
  • 解决:配置连接池
python
from sqlalchemy import create_engine
engine = create_engine(
    DATABASE_URL,
    pool_size=10,          # 连接池大小
    max_overflow=20,       # 最大超出连接数
    pool_timeout=30,       # 等待超时
    pool_pre_ping=True     # 检查连接是否有效
)

#25 内存泄漏

  • 问题:OpenClaw 进程内存持续增长
  • 解决:监控并排查内存使用
bash
# 监控内存使用
watch -n 5 "ps aux | grep openclaw"
# 如发现内存持续增长,检查:
# 1. 对话历史是否无限累积
# 2. 工具调用结果是否正确清理
# 3. 是否有循环引用

#26 时区问题

  • 问题:定时任务时间不对
  • 解决:明确指定时区
python
from datetime import datetime
import pytz

# 正确:明确指定时区
tz = pytz.timezone('Asia/Shanghai')
now = datetime.now(tz)
schedule_time = tz.localize(datetime(2026, 3, 10, 9, 0))

#27 文件路径在不同 OS 上的差异

  • 问题:Windows 上写死了 /home/user,Linux 上用了 C:\
  • 解决:使用 pathlib 处理跨平台路径
python
from pathlib import Path

base_dir = Path.home() / ".openclaw"
config_file = base_dir / "openclaw.json"
# pathlib会自动处理不同OS的路径分隔符

#28 编码问题导致工具崩溃

  • 问题:工具处理非 UTF-8 内容时崩溃
  • 解决:确保返回 UTF-8 字符串
python
def search_chinese_content(query: str) -> str:
    result = external_api_call(query)
    # 确保返回UTF-8字符串
    if isinstance(result, bytes):
        result = result.decode('utf-8', errors='replace')
    return result

#29 权限不足导致文件操作失败

  • 问题:Agent 无法读写数据目录
  • 解决:设置正确的文件权限
bash
# Linux/Mac环境
chmod 755 /path/to/openclaw/data/
chown -R openclaw:openclaw /path/to/openclaw/
# Docker环境
USER openclaw  # Dockerfile中指定用户

#30 日志文件撑满磁盘

  • 问题:日志文件无限增长,磁盘空间不足
  • 解决:配置日志轮转
yaml
// openclaw.json - 日志配置
logging:
  level: "info"           # 不要用debug(产生太多日志)
  maxFileSize: "100MB"    # 单个日志文件上限
  maxFiles: 10            # 保留最近10个日志文件
  compress: true          # 压缩旧日志

16.3 业务逻辑类踩坑(#31-#45)

#31 Agent 做了用户不期望的操作

  • 问题:Agent 自作主张发送了邮件/消息
  • 解决:在 SOUL.md 中添加确认机制

"执行任何外部操作(发送消息、修改数据)前,先告知用户你将要做什么,等待用户确认后再执行。"

#32 多 Agent 协作时角色混乱

  • 问题:多个 Agent 职责不清,互相越权
  • 解决:通过独立 workspace 和工具权限隔离角色
json
{
  "agents": {
    "list": [
      {
        "id": "coordinator",
        "name": "协调员",
        "workspace": "~/.openclaw/workspace-coordinator",
        "tools": { "deny": ["exec", "write"] }
      },
      {
        "id": "researcher",
        "name": "研究员",
        "workspace": "~/.openclaw/workspace-researcher",
        "tools": { "allow": ["read", "group:runtime"] }
      },
      {
        "id": "executor",
        "name": "执行者",
        "workspace": "~/.openclaw/workspace-executor",
        "tools": { "allow": ["group:fs", "group:runtime"] }
      }
    ]
  }
}

#33 重要决策依赖单一 Agent

  • 问题:Agent 判断错误导致业务损失
  • 解决:关键决策需要双 Agent 确认
  • 架构:决策 Agent -> 验证 Agent -> 执行

#34 用户数据隔离不当

  • 问题:多用户场景下 A 用户看到了 B 用户的数据
  • 解决:每个用户独立的 memory 目录和对话上下文

#35 Agent 输出未过滤敏感信息

  • 问题:Agent 返回内容中包含手机号、身份证等 PII 信息
  • 解决:在返回结果前过滤敏感信息
python
import re

def sanitize_output(text: str) -> str:
    # 过滤手机号
    text = re.sub(r'1[3-9]\d{9}', '***手机号***', text)
    # 过滤身份证
    text = re.sub(r'\d{17}[\dX]', '***身份证***', text)
    # 过滤银行卡号
    text = re.sub(r'\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}', '***银行卡***', text)
    return text

#36 Agent 不知道今天日期

  • 问题:Agent 回答日期相关问题时不准确
  • 解决:SOUL.md 中动态注入 今天是{date}

#37 翻译质量差

  • 问题:翻译结果生硬、不自然
  • 解决:指定源语言和目标语言,提供专业术语表

#38 长任务中途失败

  • 问题:处理到一半时失败,需要从头开始
  • 解决:实现 checkpoint 机制,支持断点续传

#39 Agent 假装完成任务

  • 问题:Agent 声称已完成但实际未执行
  • 解决:要求 Agent 返回可验证的结果(URL/ID/数据)

#40 工具调用顺序错误

  • 问题:Agent 没有按正确流程调用工具
  • 解决:SOUL.md 中明确工作流顺序

#41 响应时间过长

  • 问题:用户等待时间太久
  • 解决:拆分大任务为小任务,流式返回进度

#42 重复调用相同工具

  • 问题:相同输入重复请求,浪费资源
  • 解决:工具结果缓存,相同输入直接返回缓存

#43 格式输出不稳定

  • 问题:Agent 有时返回 JSON 有时返回纯文本
  • 解决:用 JSON Schema 约束输出格式

#44 外部链接无法访问

  • 问题:Agent 调用的外部 URL 不可达
  • 解决:检查网络/代理配置,测试 DNS 解析

#45 多语言混用导致理解偏差

  • 问题:中英文混合 prompt 导致 Agent 理解不一致
  • 解决:固定使用中文或英文,不混用

16.4 性能优化类踩坑(#46-#50)

#46 首次响应太慢

  • 问题:Agent 启动后第一次响应延迟很高
  • 解决
    1. 预热:Agent 启动时发送一条测试消息预热连接
    2. 缓存:常见问题的回答提前缓存
    3. 流式:开启 streaming 返回,让用户看到实时输出

#47 工具超时导致整体失败

  • 问题:单个工具超时拖垮整个任务
  • 解决:配置工具级别的超时和降级策略
json
{
  "tools": {
    "defaultTimeout": 15,      // 工具默认15秒超时
    "retryOnTimeout": true,
    "maxRetries": 2,
    "fallbackOnFailure": "返回错误信息,继续其他任务"
  }
}

#48 数据库查询慢

  • 问题:Agent 查询数据库响应缓慢
  • 解决:为常用查询字段添加索引,监控慢查询
sql
-- 为常用查询字段添加索引
CREATE INDEX idx_user_id ON conversations(user_id);
CREATE INDEX idx_created_at ON messages(created_at);
-- 监控慢查询
EXPLAIN ANALYZE SELECT * FROM messages WHERE user_id = 123;

#49 图片处理耗时

  • 问题:上传大图片导致处理缓慢
  • 解决:上传图片前压缩
python
from PIL import Image
import io

def compress_image(image_path: str, max_size: int = 1024) -> bytes:
    img = Image.open(image_path)
    img.thumbnail((max_size, max_size))
    buffer = io.BytesIO()
    img.save(buffer, format='JPEG', quality=85)
    return buffer.getvalue()

#50 监控告警太多(警报疲劳)

  • 问题:告警泛滥导致真正的问题被忽略
  • 解决:分级告警,避免狼来了效应
yaml
# 分级告警,避免狼来了效应
alerts:
  critical:   # 立即处理(短信+电话)
    - api_down
    - cost_limit_80pct
  warning:    # 24小时内处理(邮件)
    - error_rate_high
    - latency_spike
  info:       # 每周汇总(报告)
    - daily_usage_summary
    - model_performance

日志管理

bash
# 实时查看日志
openclaw logs --follow

# 最近 100 条
openclaw logs --limit 100

# JSON 格式输出(便于分析)
openclaw logs --json

# 只看错误
openclaw logs --level error

配置日志级别:

json
{
  "gateway": {
    "logging": {
      "level": "info"
    }
  }
}

开发调试时可设为 debug,生产环境建议使用 infowarn

性能优化

如果 Agent 响应变慢:

优化项方法
减少活跃技能openclaw skills disable <不常用的技能>
使用更快的模型简单任务切换到 DeepSeek V3 或 Gemini Flash
启用缓存减少重复 API 调用
增大心跳间隔减少后台 Token 消耗
清理历史对话定期清理 30 天前的记忆文件

Bot 不回消息的 3 步排查

这是最常见的问题。按以下顺序排查:

1. 检查 Gateway 是否运行

bash
openclaw status

如果 Gateway 没运行,先启动它。

2. 查看日志

bash
openclaw logs --tail 50

根据日志中的错误信息判断问题:

  • 看到 ECONNREFUSEDtimeout → 网络代理问题
  • 看到 401 Unauthorized → API Key 错误
  • 看到 rate limit → API 额度用完了

3. 测试模型连接

bash
openclaw agent --message "测试" --thinking high

如果这一步能收到回复,说明模型连接正常,问题出在聊天平台那一层。

端口被占用

报错:Error: listen EADDRINUSE: address already in use :::18789

bash
# 找到占用端口的进程
lsof -i :18789

# 杀掉进程(PID 是上一步查到的数字)
kill -9 <pid>

# 重启 OpenClaw
openclaw restart

Telegram 配对失败

如果 Bot 创建了但配对不上:

bash
# 查看配对码
openclaw pairing list

# 手动批准配对
openclaw pairing approve telegram <你的Telegram User ID>

你的 User ID 可以在 Telegram 搜索 @userinfobot 获取。

还是无法解决?

如果以上内容都无法帮助你解决问题:

  1. 运行 openclaw doctor 并保存输出
  2. 运行 openclaw logs --follow 复现问题并保存日志
  3. GitHub Issues 提交问题,附上以上信息

社区资源

  • GitHub Issues — 搜索已有问题或提交新问题
  • Discord 社区 — 实时交流和问答
  • Datawhale 中文社区 — 国内用户互助
觉得有帮助?