SMS

OpenClaw 可以通过 Twilio 电话号码或 Messaging Service 接收和发送 SMS。Gateway 网关会注册入站 webhook 路由，默认验证 Twilio 请求签名，并通过 Twilio 的 Messages API 发回回复。

开始之前

你需要：

• 已使用 openclaw plugins install @openclaw/sms 安装官方 SMS 插件。
• 一个 Twilio 账户，并带有支持 SMS 的电话号码，或一个 Twilio Messaging Service。
• Twilio Account SID 和 Auth Token。
• 一个可以访问你的 OpenClaw Gateway 网关的公开 HTTPS URL。
• 一个发送方策略选择：pairing 用于私人使用，allowlist 用于预先批准的电话号码，或仅在有意公开 SMS 访问时使用 open。

如果号码同时具备 SMS 和语音通话能力，请将同一个 Twilio 号码同时用于 SMS 和 Voice Call。在 Twilio 中分别配置 SMS webhook 和 Voice webhook；本页只介绍 SMS webhook。

快速设置

openclaw plugins install @openclaw/sms

{channels: {sms: {  enabled: true,  accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  authToken: "twilio-auth-token",  fromNumber: "+15551234567",  publicWebhookUrl: "https://gateway.example.com/webhooks/sms",  dmPolicy: "pairing",},},}

openclaw config patch --file ./sms.patch.json5 --dry-runopenclaw config patch --file ./sms.patch.json5

https://gateway.example.com/webhooks/sms

tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/smstailscale funnel status

openclaw gateway

openclaw pairing list smsopenclaw pairing approve sms <CODE>

配置示例

配置文件

当你希望渠道定义随 Gateway 网关配置一起移动时，请使用配置文件设置：

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

环境变量

对于密钥来自主机环境的单账户部署，请使用环境变量设置：

export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"export TWILIO_AUTH_TOKEN="<twilio-auth-token>"export TWILIO_PHONE_NUMBER="+15551234567"export SMS_PUBLIC_WEBHOOK_URL="https://gateway.example.com/webhooks/sms"

然后在配置中启用该渠道：

{  channels: {    sms: {      enabled: true,      dmPolicy: "pairing",    },  },}

TWILIO_SMS_FROM 可作为 TWILIO_PHONE_NUMBER 的别名。当 Twilio 应从 Messaging Service 中选择发送方时，请使用 TWILIO_MESSAGING_SERVICE_SID 而不是电话号码发送方。

SecretRef 认证令牌

authToken 可以是 SecretRef。当 Gateway 网关应从 OpenClaw 密钥运行时解析 Twilio Auth Token，而不是存储明文配置时，请使用此方式：

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: { source: "env", provider: "default", id: "TWILIO_AUTH_TOKEN" },      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

引用的环境变量或密钥提供商必须对 Gateway 网关运行时可见。更改主机环境变量后，请重启托管的 Gateway 网关进程。

仅允许列表的私人号码

当只有已知电话号码应能与智能体对话时，请使用 allowlist：

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "allowlist",      allowFrom: ["+15557654321"],    },  },}

Messaging Service 发送方

当 Twilio 应通过 Messaging Service 选择发送方时，请使用 messagingServiceSid 而不是 fromNumber：

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

如果在配置和环境变量解析后同时存在 fromNumber 和 messagingServiceSid，则会使用 fromNumber。

默认出站目标

当自动化或智能体发起的投递在发送流程省略显式目标时应有默认目的地，请设置 defaultTo：

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      defaultTo: "+15557654321",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",    },  },}

访问控制

channels.sms.dmPolicy 控制直接 SMS 访问：

• pairing（默认）
• allowlist（要求 allowFrom 中至少有一个发送方）
• open（要求 allowFrom 包含 "*"）
• disabled

allowFrom 条目应为 E.164 电话号码，例如 +15551234567。sms: 前缀会被接受并规范化。对于私人助手，建议使用带有显式电话号码的 dmPolicy: "allowlist"。

发送 SMS

出站 SMS 目标使用 sms: 服务前缀，并选择 SMS 渠道：

openclaw message send --channel sms --target sms:+15551234567 --message "hello"

当渠道选择是隐式的，twilio-sms:+15551234567 会选择此渠道，而不会接管 iMessage 使用的现有渠道所有的 sms: 服务前缀。

openclaw message send --target twilio-sms:+15551234567 --message "hello"

CLI 要求显式 --target。defaultTo 用于自动化和智能体发起的投递路径，其中目标可从渠道配置解析。

来自入站 SMS 对话的智能体回复会自动通过配置的 Twilio 发送方返回给发送方。

SMS 输出是纯文本。OpenClaw 会去除 markdown，展平围栏代码块，保留可读链接，并在通过 Twilio 发送前对长回复进行分块。

验证设置

Gateway 网关启动后：

1. 确认 Gateway 网关日志显示 SMS webhook 路由。
2. 运行 Twilio 侧探测：

openclaw channels capabilities --channel smsopenclaw channels status --channel sms --probe --json

3. 从你的手机向 Twilio 号码发送 SMS。
4. 运行 openclaw pairing list sms。
5. 使用 openclaw pairing approve sms <CODE> 批准配对码。
6. 再发送一条 SMS 并确认智能体回复。

对于仅出站测试，请使用：

openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"

从 macOS iMessage/SMS 进行端到端测试

在可以通过 Messages 发送运营商 SMS 的 Mac 上，你可以使用 imsg 驱动发送方，而无需触碰手机：

imsg send --to "+15551234567" --service sms --text "OpenClaw SMS E2E $(date -u +%Y%m%dT%H%M%SZ)" --jsonopenclaw pairing list smsopenclaw pairing approve sms <CODE>imsg send --to "+15551234567" --service sms --text "reply exactly SMS pong" --json

第一条消息应创建配对请求。第二条消息应通过 Twilio 收到智能体回复。

Webhook 安全

默认情况下，OpenClaw 使用 publicWebhookUrl 和 authToken 验证 X-Twilio-Signature。请保持 publicWebhookUrl 与 Twilio 中配置的 URL 逐字节一致，包括 scheme、host、path 和 query string。

仅用于本地隧道测试时，你可以设置：

{  channels: {    sms: {      dangerouslyDisableSignatureValidation: true,    },  },}

不要在公开 Gateway 网关上使用已禁用的签名验证。

多账户配置

当你运营多个 Twilio 号码时，请使用 accounts：

{  channels: {    sms: {      accounts: {        support: {          enabled: true,          accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",          authToken: "twilio-auth-token",          fromNumber: "+15551234567",          publicWebhookUrl: "https://gateway.example.com/webhooks/sms/support",          webhookPath: "/webhooks/sms/support",          dmPolicy: "allowlist",          allowFrom: ["+15557654321"],        },      },    },  },}

每个账户都应使用不同的 webhookPath。

故障排除

Twilio 返回 403 或 OpenClaw 拒绝 webhook

检查 publicWebhookUrl 是否与 Twilio 中配置的 URL 完全匹配，包括 scheme、host、path 和 query string。Twilio 会对公开 URL 字符串签名，因此代理重写和备用主机名可能会破坏签名验证。

没有出现配对请求

检查 Twilio 号码的 Messaging webhook URL 和方法。它必须指向 SMS webhook URL 并使用 POST。还要确认 Gateway 网关可从公网或通过你的隧道访问。

如果 Twilio 消息日志显示错误 11200，说明 Twilio 已接受入站 SMS，但无法访问你的 webhook。检查：

• Twilio Messaging > A message comes in 指向 publicWebhookUrl。
• 方法是 POST。
• 隧道或反向代理暴露准确的 webhookPath；对于 Tailscale Funnel，运行 tailscale funnel status 并确认列出了 /webhooks/sms。
• publicWebhookUrl 使用与 Twilio 发送的一致的 scheme、host、path 和 query string，这样签名验证才能复现已签名的 URL。

出站发送失败

确认 accountSid、authToken，以及 fromNumber 或 messagingServiceSid 已解析。如果你使用试用版 Twilio 账户，则可能需要先在 Twilio 中验证目标号码，才能发送出站 SMS。

消息已到达但智能体没有回答

检查 dmPolicy 和 allowFrom。使用默认的 pairing 策略时，必须先批准发送者，才会处理正常的智能体轮次。