LLM Wiki
原始来源（不可变）

OpenClaw 运维手册

文件路径：raw/tech-docs/OpenClaw运维手册.md

OpenClaw 运维手册

本文档记录了 OpenClaw 使用过程中可能遇到的各类问题、症状识别及解决方案。

目录

环境要求

基础网络参数

参数 标准值 说明
Clash 代理端口 127.0.0.1:7897 必须保持畅通
Gateway 端口 18789 飞书事件订阅地址
Node.js 版本 v24.13.1 通过 fnm 管理

Clash 绕过配置

以下国内域名不需要代理：

localhost,127.0.0.1
*.feishu.cn,*.larksuite.com
open.bigmodel.cn,*.moonshot.cn,*.zhipuai.cn

常见问题分类

网络类问题

1. 网络连接错误（network_error）

错误信息：

Unhandled stop reason: network_error

可能原因：

  1. 代理未启动：Clash 代理未启动或端口不通
  2. 上下文超限：对话历史过长，超过模型上下文窗口
  3. 服务故障：Zhipu GLM 等服务暂时不可用

解决方案：

# 检查 Clash 是否运行
lsof -i:7897

# 检查代理连通性
curl -v http://127.0.0.1:7897
  • 如对话过长，开启新话题（/new）
  • 如模型故障，等待或切换其他模型

预防措施：

  • 定期监控 Clash Verge 运行状态
  • 长对话及时总结或开启新话题
  • 配置多个模型作为备用

2. 搜索功能失败（fetch failed）

错误信息：

Error: fetch failed

出现场景：仅在使用 web_search 工具时出现

原因：Node.js 原生 fetch 不支持 HTTP_PROXY 环境变量

解决方案：

创建 ~/.openclaw/proxy-preload.js：

const { fetch: undiciFetch, EnvHttpProxyAgent } = require('/Users/laoyangtou/.local/share/fnm/node-versions/v24.13.1/installation/lib/node_modules/openclaw/node_modules/undici');
const proxyAgent = new EnvHttpProxyAgent();
globalThis.fetch = function(url, options = {}) {
  return undiciFetch(url, options);
};
console.log('[OpenClaw Proxy] 已覆盖全局 fetch 使用 undici with EnvHttpProxyAgent');

确保 LaunchAgent plist 中 NODE_OPTIONS 包含：

<string>-r /Users/laoyangtou/.openclaw/proxy-preload.js</string>

配置类问题

3. 配置无效（Config invalid）

错误信息 A：

Config invalid: Unrecognized key: mcp

错误信息 B：

Config invalid: Unrecognized key: label

原因：配置文件 openclaw.json 中包含已废弃的配置键

解决方案：

编辑 ~/.openclaw/openclaw.json，删除或注释以下内容：

// 删除 agents.list 中的 mcp 字段
"agents": {
  "list": [
    {
      // 删除这一行: "mcp": "..."
    }
  ]
}

// 删除 bindings 中的 label 字段
"bindings": [
  {
    // 删除这一行: "label": "..."
  }
]

4. 默认账号未配置

错误信息：

Feishu account 'default' not configured

原因：channels.feishu.accounts 中包含未配置的 default 账号

解决方案：

"channels": {
  "feishu": {
    "accounts": {
      // 删除以下重复项：
      // "default": { }
      "main": { ... },
      "content": { ... },
      "commercial": { ... }
    }
  }
}

⚠️ 注意：此问题具有周期性复发特征，每次升级后需检查。

5. 插件重复

错误信息：

Duplicate feishu plugin detected

原因：~/.openclaw/extensions/feishu/ 目录与内置插件冲突

解决方案：

# 删除冲突目录
rm -rf ~/.openclaw/extensions/feishu/

服务类问题

6. 服务未找到（Service not found）

错误信息：

Service unit not found
Gateway 无法启动

原因：LaunchAgent 配置丢失或版本升级后未重新注册

解决方案：

# 重新注册服务
openclaw gateway install

# 启动服务
openclaw gateway start

# 检查状态
openclaw gateway status

⚠️ 重要：每次运行 install 后，代理配置会被重置，需要手动恢复！

7. 代理配置被覆盖

症状：修复后仍然无法连接外网，或国内 API 走了代理

原因：openclaw gateway install 会覆盖 LaunchAgent plist 文件

解决方案：

重新编辑 ~/Library/LaunchAgents/ai.openclaw.gateway.plist，在 EnvironmentVariables 中添加：

<key>HTTP_PROXY</key>
<string>http://127.0.0.1:7897</string>
<key>HTTPS_PROXY</key>
<string>http://127.0.0.1:7897</string>
<key>http_proxy</key>
<string>http://127.0.0.1:7897</string>
<key>https_proxy</key>
<string>http://127.0.0.1:7897</string>
<key>NO_PROXY</key>
<string>localhost,127.0.0.1,*.feishu.cn,*.larksuite.com,open.bigmodel.cn,*.moonshot.cn,*.zhipuai.cn</string>
<key>NODE_OPTIONS</key>
<string>-r /Users/laoyangtou/.openclaw/proxy-preload.js</string>

然后重启服务：

openclaw gateway restart

日常巡检清单

每日检查

  • Clash Verge 正常运行（菜单栏图标存在）
  • OpenClaw Gateway 状态正常 
    openclaw gateway status
  • 测试一条简单消息，确认响应正常

每周检查

  • 查看日志是否有异常 
    tail -50 ~/.openclaw/logs/gateway.log
tail -50 ~/.openclaw/logs/gateway.err.log
  • 检查配置文件是否有被意外修改
  • 清理过长的对话历史

每月检查

  • 备份 ~/.openclaw/openclaw.json
  • 检查 LaunchAgent plist 配置完整性
  • 更新 Clash 规则和节点

故障排查流程

快速诊断流程

OpenClaw 不响应
 │
 ├── 检查 Gateway 状态
 │   └── openclaw gateway status
 │       │
 │       ├── 未运行 → 启动服务
 │       │   └── openclaw gateway start
 │       │
 │       └── 运行中 → 检查日志
 │           └── tail -f ~/.openclaw/logs/gateway.err.log
 │               │
 │               ├── network_error → 检查 Clash 代理
 │               │   └── lsof -i:7897
 │               │       │
 │               │       ├── 无输出 → 启动 Clash Verge
 │               │       │
 │               │       └── 有输出 → 重启 Gateway
 │               │           └── openclaw gateway restart
 │               │
 │               ├── Config invalid → 修复配置文件
 │               │   └── 参考"配置无效"章节
 │               │
 │               └── model_context_window_exceeded
 │                   └── 开启新对话
 │
 └── 飞书收不到消息
     └── 检查 WebSocket 连接
         └── grep "ws client" ~/.openclaw/logs/gateway.log

可视化流程图

OpenClaw故障排查流程图

终端风格的故障排查流程图，可直接用于快速诊断

一键重启脚本

#!/bin/bash
# openclaw-restart.sh

echo "=== OpenClaw 重启程序 ==="

echo "1. 检查 Clash 代理..."
if lsof -i:7897 > /dev/null 2>&1; then
  echo "  ✓ Clash 运行正常"
else
  echo "  ✗ Clash 未启动，请启动 Clash Verge"
  exit 1
fi

echo "2. 重启 Gateway..."
openclaw gateway restart
sleep 2

echo "3. 检查状态..."
openclaw gateway status

echo "4. 查看最近日志..."
tail -5 ~/.openclaw/logs/gateway.log

echo "=== 重启完成 ==="

版本升级指南

升级前准备

  1. 备份配置文件：

    cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
cp ~/Library/LaunchAgents/ai.openclaw.gateway.plist ~/Library/LaunchAgents/ai.openclaw.gateway.plist.bak

  2. 记录当前代理配置：

    grep -A1 "HTTP_PROXY\|NO_PROXY\|NODE_OPTIONS" ~/Library/LaunchAgents/ai.openclaw.gateway.plist

  3. 停止服务：

    openclaw gateway stop

升级后修复

  1. 重新安装服务：

    openclaw gateway install

  2. 恢复代理配置（关键！）： 重新编辑 plist 文件，添加 HTTP_PROXY、HTTPS_PROXY、NO_PROXY、NODE_OPTIONS

  3. 启动服务：

    openclaw gateway start

  4. 验证：

    # 检查代理是否生效
grep "OpenClaw Proxy" ~/.openclaw/logs/gateway.log

# 检查飞书连接
grep "ws client ready" ~/.openclaw/logs/gateway.log

使用 Coding Agent 自动修复

对于上述常见问题，可以使用 Coding Agent（AI 编程助手）来自动诊断和修复。以下是主流工具的介绍和使用场景。

什么是 Coding Agent

Coding Agent 是一类 AI 驱动的编程助手，可以直接在终端中运行，帮助用户：

  • 🔍 诊断问题 - 分析日志、配置文件，定位故障原因
  • 🔧 自动修复 - 根据诊断结果，自动修改配置文件
  • 💬 交互式排查 - 通过对话方式引导用户完成复杂修复

主流 Coding Agent 对比

工具 开发商 特点 适用场景
Claude Code Anthropic 强大的推理能力，支持多步骤复杂任务 复杂配置修复、批量修改
Cursor Cursor Inc IDE 集成，可视化编辑，代码补全强 需要可视化确认的场景
OpenCode OpenCode AI 开源免费，轻量级，速度快 快速诊断、简单修复
Kimi CLI Moonshot 中文支持好，国内模型 中文环境下的配置修复

安装与配置

Claude Code

# 安装
npm install -g @anthropic-ai/claude-code

# 配置 API Key
export ANTHROPIC_API_KEY=your_api_key

# 在 OpenClaw 目录启动
claude ~/.openclaw

使用示例 - 自动修复配置问题：

# 让 Claude Code 检查并修复配置文件
claude ~/.openclaw --print "检查 openclaw.json 配置文件，删除所有已废弃的键（如 mcp、label），并验证 JSON 格式是否正确"

Cursor

# 下载安装
# https://cursor.sh

# 在 OpenClaw 目录打开
cursor ~/.openclaw

使用示例 - 可视化编辑 plist 文件：

  1. 打开 Cursor
  2. 使用 AI Chat："帮我检查 ai.openclaw.gateway.plist 的代理配置是否完整"
  3. 根据建议直接修改文件

OpenCode

# 安装
npm install -g @opencode-ai/opencode

# 配置
export OPENCODE_API_KEY=your_api_key

# 启动
opencode ~/.openclaw

使用示例 - 快速诊断：

opencode ~/.openclaw --command "分析 gateway.err.log 最近的错误，给出修复建议"

Kimi CLI

# 安装
npm install -g @moonshot-ai/kimi-cli

# 配置
export MOONSHOT_API_KEY=your_api_key

# 启动
kimi ~/.openclaw

使用示例 - 中文交互修复：

kimi ~/.openclaw --print "检查 OpenClaw 配置，飞书报 'default account not configured' 错误，请修复"

OpenClaw 常见问题自动修复脚本

场景 1：自动清理废弃配置键

使用 Claude Code：

claude ~/.openclaw --print '
任务：清理 openclaw.json 中的废弃配置键

需要删除的键：
1. agents.list 中的 "mcp" 字段
2. bindings 中的 "label" 字段
3. channels.feishu.accounts 中的 "default" 账号（如果为空配置）

步骤：
1. 读取 ~/.openclaw/openclaw.json
2. 检查并删除上述废弃键
3. 验证 JSON 格式
4. 保存文件
5. 输出修改摘要
'

场景 2：自动修复代理配置

使用 Cursor 或 Claude Code：

claude ~/Library/LaunchAgents --print '
任务：修复 ai.openclaw.gateway.plist 的代理配置

需要确保 EnvironmentVariables 中包含：
- HTTP_PROXY = http://127.0.0.1:7897
- HTTPS_PROXY = http://127.0.0.1:7897
- http_proxy = http://127.0.0.1:7897
- https_proxy = http://127.0.0.1:7897
- NO_PROXY = localhost,127.0.0.1,*.feishu.cn,*.larksuite.com,open.bigmodel.cn,*.moonshot.cn,*.zhipuai.cn
- NODE_OPTIONS = -r /Users/laoyangtou/.openclaw/proxy-preload.js

步骤：
1. 读取 ai.openclaw.gateway.plist
2. 检查 EnvironmentVariables 字典
3. 添加缺失的环境变量
4. 保存文件
5. 提醒用户运行：openclaw gateway restart
'

场景 3：自动诊断网络问题

使用 OpenCode：

opencode ~/.openclaw --command '
诊断 OpenClaw 网络连接问题：

1. 检查 Clash 代理是否运行（端口 7897）
2. 检查 Gateway 是否运行（端口 18789）
3. 查看最近的 gateway.err.log 错误
4. 根据错误类型给出修复建议

输出格式：
- 诊断结果
- 问题原因
- 修复命令
'

推荐工作流

日常维护：

# 每周运行一次自动检查
claude ~/.openclaw --print "检查 OpenClaw 配置健康度，列出所有潜在问题"

故障排查：

# 出现问题时，让 AI 分析日志
opencode ~/.openclaw --command "分析最近 50 行日志，找出错误原因"

升级后修复：

# 版本升级后自动恢复配置
cursor ~/.openclaw
# 然后在 AI Chat 中问："升级后需要恢复哪些配置？"

注意事项

  1. 备份优先：让 Coding Agent 修改文件前，先让它创建备份
  2. 逐步确认：复杂修复分步骤进行，每步确认后再继续
  3. 权限问题：部分文件需要管理员权限，使用 sudo 或先修改权限
  4. 验证结果：修改后手动验证，不要完全依赖 AI

快速参考卡

问题 推荐工具 命令示例
配置无效 Claude Code claude ~/.openclaw --print "修复配置"
代理问题 Cursor 可视化编辑 plist
日志分析 OpenCode opencode ~/.openclaw --command "分析日志"
中文环境 Kimi CLI kimi ~/.openclaw --print "诊断问题"
批量修改 Claude Code claude ~/.openclaw --print "批量修复"

附录

重要文件位置

文件/目录 路径
主配置文件 ~/.openclaw/openclaw.json
代理预加载脚本 ~/.openclaw/proxy-preload.js
LaunchAgent plist ~/Library/LaunchAgents/ai.openclaw.gateway.plist
日志文件 ~/.openclaw/logs/gateway.log
错误日志 ~/.openclaw/logs/gateway.err.log
插件目录 ~/.openclaw/extensions/
OpenClaw 安装目录 ~/.local/share/fnm/node-versions/v24.13.1/installation/lib/node_modules/openclaw/

常用命令速查

# 服务管理
openclaw gateway start      # 启动
openclaw gateway stop       # 停止
openclaw gateway restart    # 重启
openclaw gateway status     # 查看状态
openclaw gateway install    # 重新安装服务（注意：会重置配置）

# 日志查看
tail -f ~/.openclaw/logs/gateway.log       # 实时查看
tail -50 ~/.openclaw/logs/gateway.err.log  # 查看最近错误

# 网络诊断
curl -x http://127.0.0.1:7897 https://api.openai.com/v1/models  # 测试代理
lsof -i:7897                                                    # 检查 Clash 端口
netstat -an | grep 18789                                        # 检查 Gateway 端口