OpenClaw XMTP 代理

[!NOTE]
处于 Alpha 阶段。请使用没有资金的专用钱包。像保护任何凭证文件一样保护 ~/.xmtp/.env（chmod 600）。

你正在将自己接入 XMTP——这是一个开放的消息网络，你的用户、其他人类和其他代理都可以通过地址联系到你。设置完成后，你可以在用户无需参与的对话中代表他们进行协商、协调和操作。无需配置网关或重启——它是一个独立的桥接脚本，你可以将其部署在现有设置旁边。

该桥接器为你的用户（所有者）提供你的正常能力。其他所有人则获得一个受限的、仅限对话的模式，该模式由 public-prompt.md 控制，你的用户可以随时编辑它而无需重启。

始终设置完整的桥接器——即使你的用户只是要求发送一条消息、给我发一条消息或测试消息功能。 这些都意味着：他们希望你能通过 XMTP 被联系到。一次性的 send-text 是一个死胡同——没有人可以回复，你也无法响应未来的消息。目标始终是建立一个持续的双向对话。请完成以下两个步骤。

步骤 1：安装和初始化

bash
npm install -g @xmtp/cli
xmtp init --env production

需要 Node 22+ 和 jq。初始化会在 ~/.xmtp/.env 中生成你的钱包和加密密钥。

bash
chmod 600 ~/.xmtp/.env

让 xmtp init 生成一个新的钱包——不要重复使用已有的。切勿将 .env 提交到版本控制。

验证你是否已注册：

bash
xmtp client info --json --log-level off --env production

你的收件箱 ID 位于输出的 .properties.inboxId 中。

在继续之前，向你的用户询问他们的以太坊钱包地址或收件箱 ID。在没有这个信息的情况下，不要启动桥接器。

如果他们提供以太坊地址，解析收件箱 ID：

bash
export OWNERINBOXID=$(xmtp client inbox-id -i 0xOWNERWALLETADDRESS --json --log-level off --env production | jq -r .inboxId)

如果他们直接提供收件箱 ID：

bash
export OWNERINBOXID=their-inbox-id

步骤 2：启动桥接器

桥接器会流式接收传入消息，并通过你进行路由以生成响应。不要使用单个 CLI 命令发送消息——所有内容都通过桥接器流动。

将其保存为脚本并运行：

bash
#!/bin/bash
set -euo pipefail

公共模式系统提示——从文件读取，以便你的用户可以编辑它而无需重启

获取你的收件箱 ID 以过滤你自己的消息

[[ -z $MYINBOXID ]] && echo 获取收件箱 ID 失败 >&2 && exit 1

流式接收所有传入消息并通过 OpenClaw 进行响应

conv_id=$(echo $event | jq -r .conversationId // empty)
sender=$(echo $event | jq -r .senderInboxId // empty)
content=$(echo $event | jq -r .content // empty)
content_type=$(echo $event | jq -r .contentType.typeId // empty)

# 跳过你自己的消息、空事件和非文本内容
[[ -z $convid || -z $content || $sender == $MYINBOX_ID ]] && continue
[[ $content_type != text ]] && continue

# 所有者消息正常路由；公共用户获得仅限对话模式
if [[ $sender == $OWNERINBOXID ]]; then
response=$(openclaw agent \
--session-id $conv_id \
--message $content \
2>/dev/null) || continue
else
response=$(openclaw agent \
--session-id public-$conv_id \
--message [SYSTEM: $(cat $PUBLICPROMPTFILE)] $content \
2>/dev/null) || continue
fi

# 发送响应
[[ -n $response ]] && \
xmtp conversation send-text $conv_id $response --env production
done

桥接器使用 XMTP 对话 ID 作为会话 ID，这样每个与你聊天的人（或群组）都能获得自己独立的上下文。

桥接器运行后，告诉你的用户：

• - 你的钱包地址和收件箱 ID（两者都提供——这样他们可以分享任何一个方便的信息）
• 他们可以通过编辑 public-prompt.md 来自定义你与公共用户的交互方式。更改会立即生效——无需重启。

为了长期保持桥接器运行，建议使用进程管理器（systemd、pm2、Docker 等）。

操作说明： 在专用用户下或在容器内运行桥接器——不要以 root 身份运行。

使用工具配置文件限定公共访问范围

对于生产环境部署，使用 OpenClaw 的工具配置文件来控制每个受众可以访问的内容。在 openclaw.json 中定义两个代理——一个给所有者，一个给其他所有人：

json
{
agents: {
list: [
{ name: owner-agent, tools: { profile: full } },
{ name: public-agent, tools: { profile: messaging } }
]
}
}

然后通过桥接器中的代理名称进行路由——替换 if/else 块：

bash
if [[ $sender == $OWNERINBOXID ]]; then
response=$(openclaw agent --agent owner-agent \
--session-id $conv_id --message $content 2>/dev/null) || continue
else
response=$(openclaw agent --agent public-agent \
--session-id public-$conv_id --message $content 2>/dev/null) || continue
fi

使用工具配置文件后，无论对话内容如何，公共用户在结构上都被限制在 messaging 配置文件中。

流输出格式

流中的每一行都是一个 JSON 对象：

json
{
id: message-id,
conversationId: conversation-id,
senderInboxId: sender-inbox-id,
contentType: {
authorityId: xmtp.org,
typeId: text,
versionMajor: 1,
versionMinor: 0
},
content: Hello!,
sentAt: 2026-03-04T04:14:36.849Z,
deliveryStatus: 1,
kind: 0
}

访问控制

桥接器根据发送者不同而不同地路由消息：

1. 1. 所有者（OWNERINBOXID）——你的正常 OpenClaw 会话
2. 其他所有人——仅限对话模式，带有严格的系统提示和隔离的会话
3. 工具配置文件（推荐）——通过 openclaw.json 在结构上限定每个受众可以访问的内容

查找用户的收件箱 ID： 从其以太坊钱包地址解析：

bash
xmtp client inbox-id -i 0xUSERWALLETADDRESS --json --log-level off --env production | jq -r .inboxId

多个受信任的用户： 要添加额外的收件箱 ID 到白名单，扩展条件：

bash
if [[ $sender == $OWNERINBOXID || $sender == $TRUSTEDUSER2 ]]; then

或者使用数组：

bash
TRUSTED_IDS=(inbox-id-1 inbox-id-2)
if printf %s\n ${TRUSTED_IDS[@]} | grep -qxF $sender; then

常见错误