wa-relay

OpenClaw v0.2.0 的 WhatsApp 消息中继。将第三方 DM 路由到中继代理，中继代理通过 session_send 将它们转发到主代理。主代理通知业主并提供建议的回应。支持直接号码白名单。

# wa-relay v0.2.0

Routes third-party WhatsApp DMs through a relay agent that forwards messages to the main agent via `sessions_send`. The main agent notifies the owner and proposes a response.

## How It Works

1. **Third-party** sends a WhatsApp message
2. **Relay agent** receives it, forwards via `sessions_send` to the main agent session, and responds `NO_REPLY` (nothing sent back to the sender)
3. **Main agent** receives the inter-session message, notifies the **owner** on WhatsApp with the message and a suggested response
4. **Owner** decides: use the suggestion, modify it, or write something else
5. **Main agent** sends the response to the third party

### Direct number allowlist

Numbers in the allowlist bypass the relay entirely and go straight to the main agent (same as the owner).

## Setup

1. Run `scripts/setup.sh <owner-phone-number>` — creates relay workspace, patches main agent SOUL.md
2. Run `scripts/configure.sh <owner-phone-number> [direct-numbers]` — generates routing config
3. Apply the generated config (see `references/SETUP.md`)

## Requirements

- OpenClaw v2026.2.14+ with WhatsApp channel configured
- Owner's phone number in international format (e.g. `+573001234567`)

## Security Notes

This skill performs two actions that require elevated access. Both are necessary for multi-agent WhatsApp routing to work and are explained here for transparency:

### 1. Auth credential sharing
The setup script copies `auth-profiles.json` from the main agent to the relay agent. This is required because OpenClaw agents have isolated auth — without shared credentials, the relay agent cannot authenticate with any model provider and will silently fail. The script asks for confirmation before copying.

### 2. Session ID regex patch (temporary)
OpenClaw's session ID validator rejects `:` and `+` characters that WhatsApp phone-number routing generates (e.g. `agent:wa-relay:whatsapp:+15551234567`). The setup script patches the `SAFE_SESSION_ID_RE` regex in OpenClaw's dist files to allow these characters. This is a known bug (openclaw/openclaw#16211) with an open fix (PR #16531). Once merged, this patch becomes unnecessary and can be reverted. The script creates `.bak` backups and asks for confirmation before patching.

### 3. Main agent SOUL.md modification
The setup script appends a "Relay de WhatsApp" section to the main agent's SOUL.md so it knows how to handle forwarded messages. Review the added section after setup.

---

## 中文说明

# wa-relay v0.2.0

通过一个中继代理路由第三方 WhatsApp 私信，该中继代理通过 `sessions_send` 将消息转发给主代理。主代理通知业主并提出回应建议。

## 工作原理

1. **第三方**发送一条 WhatsApp 消息
2. **中继代理**收到消息，通过 `sessions_send` 转发到主代理会话，并回复 `NO_REPLY`（不会向发送方回传任何内容）
3. **主代理**收到跨会话消息，在 WhatsApp 上通知**业主**，附带原消息和一条建议回应
4. **业主**决定：采用建议、修改建议，或自行撰写其他内容
5. **主代理**将回应发送给第三方

### 直接号码白名单

白名单中的号码会完全绕过中继，直接转给主代理（与业主待遇相同）。

## 安装设置

1. 运行 `scripts/setup.sh <owner-phone-number>` —— 创建中继工作区，并修补主代理的 SOUL.md
2. 运行 `scripts/configure.sh <owner-phone-number> [direct-numbers]` —— 生成路由配置
3. 应用生成的配置（参见 `references/SETUP.md`）

## 环境要求

- 已配置 WhatsApp 频道的 OpenClaw v2026.2.14+
- 业主电话号码采用国际格式（例如 `+573001234567`）

## 安全说明

本技能会执行两项需要更高权限的操作。两者对于多代理 WhatsApp 路由的正常工作都是必需的，此处为透明起见加以说明：

### 1. 认证凭据共享
安装脚本会将主代理的 `auth-profiles.json` 复制到中继代理。这是必需的，因为 OpenClaw 代理的认证是相互隔离的——若没有共享凭据，中继代理将无法向任何模型提供方认证，并会静默失败。脚本在复制前会请求确认。

### 2. 会话 ID 正则修补（临时）
OpenClaw 的会话 ID 校验器会拒绝 WhatsApp 电话号码路由所生成的 `:` 和 `+` 字符（例如 `agent:wa-relay:whatsapp:+15551234567`）。安装脚本会修补 OpenClaw dist 文件中的 `SAFE_SESSION_ID_RE` 正则以允许这些字符。这是一个已知缺陷（openclaw/openclaw#16211），已有待合并的修复（PR #16531）。一旦合并，此修补即不再必要，可以回退。脚本会创建 `.bak` 备份，并在修补前请求确认。

### 3. 主代理 SOUL.md 修改
安装脚本会向主代理的 SOUL.md 追加一个 "Relay de WhatsApp" 章节，使其了解如何处理转发的消息。安装完成后请检查所添加的章节。