Claude OpenClaw Relay

牛马 Agent — 让 Claude Code 与 OpenClaw 双向互通，共享记忆、互相派发任务、互相监督升级。

简介

Claude OpenClaw Relay 是一个开源的 Agent 互通框架，让 Claude Code 和 OpenClaw 两个系统能够：

记忆同步 — 通过 Outbox + Bridge 模式共享关键结论
任务派发 — 互相发布、跟踪、完成工单
监督升级 — 心跳检测、异常自愈、自动升级触发
Skill 互评 — 跨系统评估对方 Skill 质量，提出升级建议
Agent 协调 — 两个系统的 Agent 之间接力、并行、交叉验证

┌─────────────────┐          Memory Bus          ┌─────────────────┐
│   Claude Code    │ ◄──── outbox / bridge ─────► │    OpenClaw     │
│                  │                              │                 │
│  ┌─────────────┐ │   ┌──────────────────┐      │ ┌─────────────┐ │
│  │task-receiver│ │   │ task-dispatcher  │      │ │task-receiver│ │
│  │skill-advisor│ │   │ supervisor       │      │ │skill-advisor│ │
│  │coordinator  │ │   │ memory-sync      │      │ │coordinator  │ │
│  └─────────────┘ │   └──────────────────┘      │ └─────────────┐ │
│  ┌─────────────┐ │         RELAY               │ ┌─────────────┐ │
│  │ 42 agents   │ │                              │ │ 5 agents    │ │
│  │ 100+ skills │ │                              │ │ 50+ skills  │ │
│  └─────────────┘ │                              │ └─────────────┘ │
└─────────────────┘                              └─────────────────┘

快速开始

macOS / Linux

git clone https://github.com/HM-HAO/claude-openclaw-relay.git
cd claude-openclaw-relay
bash setup.sh

Windows (PowerShell)

# 克隆仓库
git clone https://github.com/HM-HAO/claude-openclaw-relay.git
cd claude-openclaw-relay

# 一键安装
.\setup.ps1

# 如果执行策略限制，先临时放开
# Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# .\setup.ps1

配置

1. 复制环境变量模板

macOS / Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

2. 编辑 .env 文件

打开 .env 并填写你的实际配置：

# 必填：项目根目录
RELAY_PROJECT_ROOT=/path/to/your/claude-openclaw-relay
# Windows 示例:
# RELAY_PROJECT_ROOT=C:/Users/YourName/claude-openclaw-relay

Windows 路径注意: 请使用正斜杠 C:/path/... 或双反斜杠 C:\\path\\...，不要使用单反斜杠 C:\path\...（会被解析为转义字符导致路径失效）。

远程模式才需要（本地模式可留空）：
OPENCLAW_GATEWAY_API_KEY=YOUR_OPENCLAW_GATEWAY_API_KEY
CLAUDE_MCP_SERVER_TOKEN=YOUR_CLAUDE_MCP_SERVER_TOKEN
所有 YOUR_ 开头的值必须替换为你自己的配置，否则远程模式无法工作。本地模式下只需配置 RELAY_PROJECT_ROOT 即可。

3. 使用

macOS / Linux:

# 同步记忆
python relay/memory_sync.py --trigger

# 查看任务队列
python relay/task_dispatcher.py --list

# 创建任务（Claude -> OpenClaw）
python relay/task_dispatcher.py --create \
  --from claude --to openclaw \
  --type code-review \
  --title "Review auth module" \
  --priority P1

# 运行监督引擎
python relay/supervisor.py --check

# 跨系统 Skill 评估
python relay/skill_advisor.py --scan

# 使用统计（纯本地，无需网络）
python relay/usage_stats.py          # 打印统计 + 建议
python relay/usage_stats.py --json   # JSON 输出
python relay/usage_stats.py --quiet  # 仅摘要
python relay/skill_advisor.py --stats # 统计 + 建议（集成入口）

# 跨系统 Agent 协调
python relay/agent_coordinator.py --mode relay --task "refactor api"

Windows (PowerShell):

$env:RELAY_PROJECT_ROOT = "C:/path/to/claude-openclaw-relay"

# 同步记忆
python relay\memory_sync.py --trigger

# 查看任务队列
python relay\task_dispatcher.py --list

# 运行监督引擎
python relay\supervisor.py --check

核心组件

Relay 引擎（`relay/`）

文件	功能
`memory-sync.py`	记忆同步，支持主动触发和冲突检测
`task-dispatcher.py`	双向任务派发，支持优先级、依赖、重试
`supervisor.py`	监督引擎，心跳、异常检测、自动升级
`skill-advisor.py`	跨系统 Skill 评估与升级建议
`usage_stats.py`	使用统计与建议（无需网络）
`agent-coordinator.py`	跨系统 Agent 协调（接力/并行/交叉验证/负载均衡）

Agent 定义（`agents/`）

文件	系统	功能
`claude-task-receiver.md`	Claude Code	接收 OpenClaw 派发的任务
`claude-skill-advisor.md`	Claude Code	分析 OpenClaw Skill 并提出升级建议
`claude-coordinator.md`	Claude Code	与 OpenClaw 的 Agent 协调工作
`openclaw-task-receiver.md`	OpenClaw	接收 Claude Code 派发的任务
`openclaw-skill-advisor.md`	OpenClaw	分析 Claude Code Skill 并提出升级建议
`openclaw-coordinator.md`	OpenClaw	与 Claude Code 的 sub-agent 协调工作

架构原理

记忆同步

基于 Outbox + Sync-Pump 模式：

Writer → outbox/{system}-outbox/ → sync-pump 消费 → bridge/from-{system}/ → Reader

每个系统只能写入自己的 outbox
sync-pump 负责去重、冲突解决、脱敏、提升
双方通过 bridge 目录读取对方的结论

任务派发

文件驱动的工单系统：

创建工单 → tasks/pending/ → 分配 → tasks/assigned/ → 执行 → tasks/done/ | tasks/failed/

工单包含：标题、描述、优先级、类型、依赖、超时时间
支持 P0（紧急）到 P3（低优先级）
超时自动重试（最多 3 次）

Skill 互评升级

跨系统评估对方 Skill 的使用效果：

收集双方 Skill 使用数据（评分、频率、失败率）
建立 Skill 映射表（功能重叠的 Skill 配对）
根据规则生成升级建议
输出 skill-upgrade-proposal.md

Agent 协调

4 种协调模式：

模式	说明	示例
接力	A 完成 → 写结论 → B 接着做	OpenClaw 分析需求 → Claude 写代码
并行	同一任务分两边 → 各自执行 → 合并	双方同时审查同一模块
交叉验证	A 出方案 → B 审查 → 反馈 → A 改进	Claude 设计方案 → OpenClaw 审查
负载均衡	根据负载自动分配	任务发给空闲的 Agent

配置

环境变量

变量	说明	默认值
`RELAY_PROJECT_ROOT`	项目根目录	当前目录
`MEMORY_BUS_ROOT`	Memory Bus 根目录	`$RELAY_PROJECT_ROOT/ai-memory-bus`
`RELAY_TASK_DIR`	任务目录	`$RELAY_PROJECT_ROOT/tasks`
`RELAY_LOG_LEVEL`	日志级别	`INFO`

Hooks 集成

将 hooks/claude-hooks.json 合并到 ~/.claude/settings.json，将 hooks/openclaw-hooks.json 合并到 OpenClaw 的 hooks 配置中。

Message Bus / Sync Pipeline

消息通过 Outbox → Sync-Pump → Bridge 模式跨系统传递：

Writer → outbox/{system}-outbox/ → sync-pump 消费 → bridge/from-{system}/ → Reader

写入消息

通过 message_bus.py 或 memory_sync.py --write 将消息写入 {system}-outbox/：

# 主动触发同步（非交互模式，适合 cron/hook）
python relay/memory_sync.py --auto

# JSON 输出（供 CI 脚本解析）
python relay/memory_sync.py --auto --json

测试端到端消息流

powershell -ExecutionPolicy Bypass -File .\scripts\test-e2e.ps1

测试会：

创建临时消息写入 cc-outbox/
触发 --auto 同步到 bridge/from-claude/
验证去重（相同消息不重复消费）
验证异常消息移入 outbox/failed/
自动清理所有临时数据

报告输出：reports/e2e-relay-test.md

使用统计 / Usage Stats

纯本地统计，无需网络连接。数据来源于：

bridge/ — 已消费的跨系统消息
manifest/index.json — 处理历史
outbox/*/failed/ — 失败消息
coordination-reports/ — 协调模式使用记录

# 打印可读统计 + 建议
python relay/usage_stats.py

# JSON 输出（供脚本解析）
python relay/usage_stats.py --json

# 仅摘要行
python relay/usage_stats.py --quiet

# 通过 skill_advisor 统一入口
python relay/skill_advisor.py --stats

输出包含：按系统/消息类型/优先级/目的地的分布、协调模式使用次数、元数据不完整的 Agent 列表。生成基于规则的建议（如样本量不足、失败消息告警、重复数据提醒）。

注意：sample_size < 5 时统计仅供参考，待更多真实数据流入后再评估。

本地联调 / Local Relay Test

运行前提：Windows + PowerShell + Python。请确保已在仓库根目录下执行命令，建议先准备 .env（由 .env.example 复制）。

路径提醒：必须在仓库根目录运行，PowerShell 相对路径脚本依赖当前目录位置。如果在子目录运行，可能报"找不到文件"。

环境检查

cd <repository-root>
powershell -ExecutionPolicy Bypass -File .\scripts\check-env.ps1

本地联调

powershell -ExecutionPolicy Bypass -File .\scripts\test-relay.ps1

结果说明

标记	含义
`[OK]`	检查或联调项通过
`[WARN]`	存在可继续运行的告警，不阻塞联调
`[FAIL]`	存在阻塞问题，需要先修复

联调完成后会生成报告：reports/local-relay-test.md

开发

运行测试

python -m pytest tests/ -v

目录结构

claude-openclaw-relay/
├── README.md
├── LICENSE
├── .env.example
├── .gitignore
├── setup.sh              # Unix 安装脚本
├── setup.ps1             # Windows 安装脚本
├── agents/               # Agent 定义
├── relay/                # 核心引擎
│   ├── message_bus.py    # 消息契约 + 读写 + 去重 + 失败处理
│   ├── memory_sync.py    # 记忆同步（--trigger / --auto / --write / --status）
│   ├── agent_registry.py # Agent 目录扫描 + 索引生成
│   ├── task_dispatcher.py
│   ├── supervisor.py
│   ├── skill_advisor.py
│   └── agent_coordinator.py
├── hooks/               # Hooks 配置模板
├── templates/           # 模板文件
├── scripts/             # 脚本（check-env, test-relay, test-e2e）
└── tests/               # 测试

安全

本项目不包含任何密钥、API Key 或凭据
所有 .env 文件已加入 .gitignore
发布前经过 20+ 正则模式的脱敏扫描
Memory Bus 内置脱敏规则（API Key、密码、Token、私钥等）

许可证

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
agents		agents
docs		docs
hooks		hooks
relay		relay
scripts		scripts
templates		templates
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
setup.ps1		setup.ps1
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

Claude OpenClaw Relay

简介

快速开始

macOS / Linux

Windows (PowerShell)

配置

1. 复制环境变量模板

2. 编辑 .env 文件

3. 使用

核心组件

Relay 引擎（relay/）

Agent 定义（agents/）

架构原理

记忆同步

任务派发

Skill 互评升级

Agent 协调

配置

环境变量

Hooks 集成

Message Bus / Sync Pipeline

写入消息

测试端到端消息流

使用统计 / Usage Stats

本地联调 / Local Relay Test

环境检查

本地联调

结果说明

开发

运行测试

目录结构

安全

许可证

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Relay 引擎（`relay/`）

Agent 定义（`agents/`）

Packages