OpenClaw与Hermes常见问题排查与生产配置手册（附录G-N）

附录G：版本更新追踪与配置迁移指南
附录H：常见故障排查速查表（20+典型问题）
附录I：多Agent系统性能调优与调试指南
附录J：量化交易监管合规要点（A股市场）
附录K：Hermes Agent 内置工具完整清单
附录L：ACP协议部署速查表
附录M：共享记忆工具选型速查
附录N：技能一键迁移清单

附录G：版本更新追踪与配置迁移指南

G.1 版本命名规则

OpenClaw：以日期作为版本号（如 v2026.5.4），稳定版标签格式 vYYYY.M.D
Hermes：语义化版本号（如 v0.11.0）

G.2 检查当前版本

bash

# OpenClaw
openclaw --version

# Hermes
hermes --version

G.3 升级前必须备份

bash

# 备份 OpenClaw 配置和工作区
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

# 备份 Hermes 配置和工作区
cp -r ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

G.4 版本锁定方法

为避免自动升级导致不兼容，建议使用固定版本：

OpenClaw（通过npm）：

bash

npm install -g openclaw@v2026.5.4

Hermes（通过pip）：

bash

pip install hermes-agent==0.11.0

G.5 配置迁移脚本模板

当 OpenClaw 或 Hermes 升级后配置文件结构发生变动时，可使用以下脚本进行自动化迁移：

python

#!/usr/bin/env python3
# migrate_config.py
import json, yaml, shutil
from pathlib import Path

def migrate_openclaw(old_path, new_path):
    """适用于已知配置字段变更的迁移（示例）"""
    with open(old_path) as f:
        old = json.load(f)
    new = {}
    # 示例：将旧版 `gateway.bind` 字段迁移到新版 `gateway.listen`
    if 'bind' in old.get('gateway', {}):
        new['gateway'] = {'listen': old['gateway']['bind']}
    # ... 根据实际 Release Notes 补充
    with open(new_path, 'w') as f:
        json.dump(new, f, indent=2)

if __name__ == '__main__':
    # 仅在确认变更后执行
    print("请先阅读 Release Notes，确认需要迁移的字段")

G.6 常见版本变动与应对（持续更新）

变更内容	旧版本	新版本	迁移措施
ACP 连接配置字段重命名	`acp.connections[].name`	`acp.connections[].id`	手动修改配置文件或运行迁移脚本
Hermes 记忆后端默认值变更	`memory.backend: none`	默认为 `qmd`	无影响，保持使用 `qmd` 即可
OpenClaw Cron 任务时区要求	不强制时区	必须显式设置 `--tz`	为所有 cron 任务添加 `--tz Asia/Shanghai`

最新版本变动跟踪：建议订阅官方 GitHub Release 通知，并定期访问本书 GitHub 仓库的 upgrade-notes 目录。

附录H：常见故障排查速查表

H.1 安装与启动类故障

故障现象	可能原因	排查步骤	解决方案
`openclaw gateway start` 立即退出	端口被占用	`lsof -i :18789`	`kill -9 <PID>` 或修改配置中的端口号
`hermes` 命令未找到	PATH 未更新	`which hermes`	`source ~/.bashrc` 或重新加载终端
一键安装脚本下载失败	网络问题	使用 `curl -I` 测试连接	使用国内镜像或手动安装
Hermes 提示 `sqlite3` 扩展错误	SQLite 版本过低	`sqlite3 --version`	升级 SQLite 或使用 Docker 后端

H.2 消息渠道故障

故障现象	可能原因	排查步骤	解决方案
飞书机器人无回复	WebSocket 配对未完成	查看终端输出是否有配对提示	执行终端显示的配对命令
飞书配对失败	未添加 `im.message.receive_v1` 事件	检查飞书应用“事件与回调”	添加该事件并重新发布版本
Telegram 机器人无响应	Token 错误或未启动 Gateway	`hermes gateway status`	重新配置 Token 并启动 Gateway

H.3 记忆与 RAG 故障

故障现象	可能原因	排查步骤	解决方案
记忆不生效	冻结快照机制	新会话中仍读取不到	确认修改已写入文件，再启动新会话
MEMORY.md 写满无法添加	超过字符上限（2200）	`wc -c MEMORY.md`	手动精简或运行 `hermes memory prune`
QMD 检索无结果	`minSimilarity` 阈值过高	检查配置	降低阈值至 0.2 或 0.15
OpenClaw RAG 与 Hermes 记忆不能共用	技术架构不同	无需解决	按第3.4.4节方案共享数据

H.4 ACP 通信故障

故障现象	可能原因	排查步骤	解决方案
`openclaw acp call` 超时	Hermes ACP 服务未启动	`ps aux \| grep "hermes acp serve"`	启动 Hermes ACP 服务
连接被拒绝	端口错误或防火墙	`telnet localhost 50051`	检查端口并开放防火墙
版本不兼容	OpenClaw 与 Hermes ACP 版本差异	分别查看版本号	统一升级到最新稳定版

H.5 量化策略相关故障

故障现象	可能原因	排查步骤	解决方案
回测与实盘收益差距大	滑点或手续费设置不同	对比回测和实盘日志	使用第28.4节一致性检查清单
因子IC 为 NaN	数据长度不足或除零	检查因子计算脚本	确保数据期数大于等于回望窗口
风控未触发止损	`risk.pause_trading` 未正确设置	检查共享记忆中该键值	确认风控 Agent 可写入该键，交易 Agent 可读取

H.6 通用排查三板斧

bash

openclaw status --all
openclaw doctor --repair
openclaw logs --tail 50

附录I：多Agent系统性能调优与调试指南

I.1 性能指标参考阈值

指标	正常范围	需关注	严重
Agent 响应时间（P99）	< 1s	1-3s	> 3s
Cron 任务成功率	> 99%	95-99%	< 95%
Token 成本（月）	< $50	$50-200	> $200
共享记忆延迟（P99）	< 10ms	10-30ms	> 30ms

I.2 优化检查清单

是否启用了 ACP MessagePack 序列化（use_msgpack: true）？
非实时任务是否使用了 delegate 异步模式？
是否限制了子 Agent 最大并发数（max_concurrent_subagents）？
高频查询是否使用了 Redis 缓存（TTL 5分钟）？
确定性任务是否从 Hermes 迁移到了 OpenClaw？
是否启用了 contextPruning 裁剪历史上下文？

I.3 分布式追踪配置（Jaeger + OpenTelemetry）

启动 Jaeger（Docker）：

bash

docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one:latest

OpenClaw 集成（需安装 OpenTelemetry SDK，参考第17.3节）。

轻量级替代方案：使用 ACP 日志中的 trace_id 手动关联：

bash

grep "trace_id=abc123" ~/.openclaw/logs/gateway.log
grep "trace_id=abc123" ~/.hermes/logs/agent.log

I.4 常用调试命令

bash

# 查看 OpenClaw 当前队列长度
openclaw gateway stats | grep queue_length

# 查看 Hermes 活跃子 Agent
hermes subagent list

# 测试 ACP 连接延迟
time openclaw acp call --method agent/ask --params '{"task":"ping"}' --wait

# 分析 Token 使用
openclaw stats --today
hermes config get llm.token_usage

附录J：量化交易监管合规要点（A股市场）

J.1 程序化交易报告制度

根据中国证监会《证券市场程序化交易管理规定（试行）》，使用程序化交易（含 AI Agent 自动下单）的个人或机构需向证券公司报告以下信息：

信息类型	内容
身份信息	账户持有人的身份证明
策略类型	策略描述、代码托管位置（如有）
服务器位置	托管机房地址或云服务商
风控参数	最大下单频率、单笔下单金额上限
应急预案	断线、异常时的处理流程

具体要求请以证券公司营业部通知为准，建议在实盘交易前咨询开户券商。

J.2 异常交易行为监控指标

上交所/深交所重点监控的异常行为（系统应内置检测机制）：

行为	描述	Agent 中应设置的硬限制
频繁报撤单	全日撤单率 > 50%	交易 Agent 单日撤单次数 ≤ 3 次
大额对倒	自买自卖	禁止自成交（通过订单去重）
虚假申报	不以成交为目的的大额申报	单笔委托金额不得超过账户净值的 10%
日内开仓限额	股指期货产品（如中金所规定 500 手/日）	风控 Agent 统计每日下单手数，超限熔断

J.3 日志保存期限

根据《证券法》及监管要求：

交易委托记录、撤单记录、成交记录必须保存 至少 20 年
日志存储格式：不可篡改（如 WORM 存储或带签名校验的 JSONL）
建议实现每日自动归档到云存储（OSS/S3）

J.4 跨境合规提示

如通过 Agent 连接境外交易所（如美股、港股），还需遵守当地监管：

美国 SEC Rule 15c3-5：要求市场接入控制（MAP），防止错误订单送达
香港 SFC：程序化交易必须有实时监控和熔断机制

J.5 合规检查 Skill 示例

markdown

---
name: compliance_check
description: 每日扫描审计日志，标记可疑行为并生成合规报告
---

## 执行步骤
1. 读取最近 24 小时的交易日志
2. 计算撤单率，若超过 20% 则告警
3. 检查有无自成交嫌疑（同一证券的买卖订单来自同一策略）
4. 统计日内开仓手数，接近限额时预警
5. 输出合规报告到飞书群

附录K：Hermes Agent 内置工具完整清单

Hermes Agent 预装了以下工具集（基于 v0.11.0，具体数量以实际版本为准）。工具可通过 hermes tools list 查看，工具集可通过 disabled_toolsets 配置禁用。

工具集	工具名称	功能简述	是否默认启用
terminal	`exec`	执行系统命令	是
file	`read`	读取文件	是
	`write`	写入文件	是
	`edit`	编辑文件（diff模式）	是
	`apply_patch`	应用补丁	是
web	`web_search`	搜索引擎查询	是
	`web_fetch`	获取网页内容	是
browser	`browser_navigate`	导航到 URL	是（需配置）
	`browser_click`	点击元素	是
	`browser_type`	输入文本	是
	`browser_snapshot`	获取 DOM 快照	是
memory	`memory_search`	搜索记忆	是
	`memory_store`	存储记忆	是
	`memory_list`	列表记忆	是
	`memory_forget`	删除记忆	是
skills	`skill_manage`	创建/修改/删除 Skill	是
delegation	`delegate_task`	委托子 Agent	是
cron	`cron_add`	添加定时任务	是
	`cron_remove`	删除定时任务	是
	`cron_list`	列出任务	是
messaging	`message_send`	发送消息（渠道）	是
media	`image_generate`	图像生成	是
	`tts`	文字转语音	是
code_execution	`python_repl`	Python 代码执行（隔离）	是
vision	`analyze_image`	图像分析与 OCR	是
rag	`vector_search`	向量检索	是（需配置）
rl	`export_trajectory`	导出 RL 训练数据	否（需手动启用）
homeassistant	`ha_call_service`	调用 Home Assistant	否

完整的工具参数和用法请参考 hermes tool describe <工具名>。

附录L：ACP协议部署速查表

L.1 直连模式 vs 网关中转模式

模式	OpenClaw 配置	Hermes 配置	适用场景
直连模式（stdio）	`transport: "stdio"`	`hermes acp serve`（无额外参数）	同一主机，最简配置
直连模式（TCP）	`transport: "tcp"` + `address`	`hermes acp serve --listen tcp://0.0.0.0:50051`	同一内网低延迟
网关中转模式	连接 Nginx/Envoy 地址	同 TCP，但暴露给代理	跨 VPC、需 TLS、负载均衡

L.2 直连模式 stdio 完整配置示例

OpenClaw openclaw.json：

json

{
  "acp": {
    "connections": [
      {
        "name": "hermes",
        "transport": "stdio",
        "command": "hermes",
        "args": ["acp", "serve"],
        "timeout": 60,
        "retry": { "max_attempts": 3 }
      }
    ]
  }
}

启动 Hermes ACP 服务（在同一终端或后台）：

bash

hermes acp serve

L.3 直连模式 TCP 完整配置示例

OpenClaw：

json{
“acp”: {
“connections”: [
{
“name”: “hermes-tcp”,
“transport”: “tcp”,
“address”: “192.168.1.100:50051”,
“tls”: false,
“timeout”: 30
}
]
}
}

Hermes：

bash

hermes acp serve --listen tcp://0.0.0.0:50051

L.4 防火墙与企业内网部署要点

端口要求：默认 50051，确保防火墙开放该端口的入站连接（TCP）
TLS 加密（生产环境强烈推荐）：jsontls”: true, “cert_file”: “/path/to/cert.pem”, “key_file”: “/path/to/key.pem”
代理穿透：若企业网络要求出站走 HTTP 代理，ACP 可通过 HTTP_PROXY 环境变量工作，但不保证稳定，建议优先使用 stdio 模式。

L.5 验证 ACP 连接的命令

bash

# 从 OpenClaw 端测试
openclaw acp call --connection hermes --method agent/ask --params '{"task":"ping"}' --wait

# 查看连接状态
openclaw acp status

附录M：共享记忆工具选型速查

M.1 工具对比表

工具	类型	优点	缺点	适用场景
共享文件（JSON/YAML）	文件	简单、可读、版本控制	并发需加锁	小团队、个人、非高频
Redis	内存数据库	高性能、支持过期、原子操作	额外依赖、内存成本	高频读写、实时共享
SQLite	嵌入式数据库	支持并发、SQL查询	单机部署	中等数据量、结构化记忆
PostgreSQL	关系型数据库	功能强大、事务支持	运维成本	企业级、需要永久存储
Hindsight	知识图谱	高检索精度、`reflect` 洞察	需本地 PostgreSQL	跨 Agent 经验蒸馏
Mem0	语义记忆	自动提取事实、零延迟预取	云端付费	自然语言记忆

M.2 Redis 配置示例（推荐）

yaml

# ~/docker-compose.yml
redis:
  image: redis:7-alpine
  ports:
    - "6379:6379"
  command: redis-server --appendonly yes

OpenClaw/Hermes 统一连接：

yaml

memory:
  redis:
    host: localhost
    port: 6379
    db: 0

M.3 SQLite 配置示例（轻量级）

python

import sqlite3
conn = sqlite3.connect('/mnt/shared_memory/memory.db')
conn.execute('CREATE TABLE IF NOT EXISTS shared (key TEXT PRIMARY KEY, value TEXT)')

M.4 选型决策树

仅本机单 Agent → 共享文件
本机多 Agent → SQLite 或 Redis
跨机器多 Agent → Redis（网络）或 PostgreSQL
需要语义搜索/记忆蒸馏 → Hindsight / Mem0

附录N：技能一键迁移清单

N.1 迁移命令

bash

# Dry-run 预览
hermes claw migrate --source ~/.openclaw/workspace/skills --dry-run

# 执行迁移
hermes claw migrate --source ~/.openclaw/workspace/skills

N.2 迁移前检查清单

OpenClaw 工作区路径是否正确（默认 ~/.openclaw/workspace/skills）

目标 Hermes 技能目录（~/.hermes/skills）是否有写权限
是否已有同名 Skill（迁移会跳过，不会覆盖）
是否需要指定 --target 目录（默认自动识别）

N.3 迁移后验证步骤

运行 hermes skills list 查看已迁移的 Skill 是否出现
手动测试一个简单的迁移 Skill（如 weather）
检查是否有环境变量缺失（如 OPENWEATHER_API_KEY）
检查 Skill 依赖的脚本（scripts/）是否可执行

N.4 兼容性说明

OpenClaw Skill 特性	Hermes 兼容性	处理方式
`AGENTS.md` 风格 frontmatter	部分兼容	自动转换为 `SKILL.md` 格式
`scripts/` 中的 Python/Shell 脚本	完全兼容	直接复制
`references/` 文档	完全兼容	直接复制
依赖环境变量（如 API Key）	需手动添加	迁移后需将变量复制到 `~/.hermes/.env`
OpenClaw 特有工具（如 `openclaw_send_message`）	不兼容	需改用 Hermes 的 `message_send` 工具或通过 ACP 回调

N.5 迁移后常见问题与解决

问题	原因	解决方案
Skill 未出现在列表中	frontmatter 格式不符	手动添加 `---` 包裹的 YAML 头
执行报错 `command not found`	脚本依赖的二进制不在 PATH	修改 `SKILL.md` 使用绝对路径或安装依赖
环境变量未加载	未迁移 `.env`	手动将 OpenClaw `.env` 中的密钥复制到 Hermes `.env`
工具不存在	调用了 OpenClaw 专有工具	修改 Skill 使用 Hermes 工具（见附录K）或通过 ACP 回调