@@ -20,15 +20,35 @@ OpenClaw can receive and send SMS through a Twilio phone number or Messaging Ser
2020 </Card>
2121</CardGroup>
222223-## Quick setup
23+## Before you begin
24+25+You need:
26+27+- A Twilio account with an SMS-capable phone number, or a Twilio Messaging Service.
28+- The Twilio Account SID and Auth Token.
29+- A public HTTPS URL that reaches your OpenClaw Gateway.
30+- A sender policy choice: `pairing` for private use, `allowlist` for preapproved phone numbers, or `open` only for intentionally public SMS access.
31+32+Use one Twilio number for both SMS and Voice Call if the number has both capabilities. Configure the SMS webhook and Voice webhook separately in Twilio; this page only covers the SMS webhook.
33+34+## Quick Setup
24352536<Steps>
2637 <Step title="Create or choose a Twilio sender">
27-In Twilio, choose an SMS-capable phone number or Messaging Service. Save the Account SID, Auth Token, and sender value.
38+In Twilio, open **Phone Numbers > Manage > Active numbers** and choose an SMS-capable number. Save:
39+40+- Account SID, for example `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
41+- Auth Token
42+- Sender phone number, for example `+15551234567`
43+44+If you use a Messaging Service instead of a fixed sender number, save the Messaging Service SID, for example `MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
45+2846 </Step>
29473048 <Step title="Configure the SMS channel">
314950+Save this as `sms.patch.json5` and change the placeholders:
51+3252```json5
3353{
3454 channels: {
@@ -44,13 +64,17 @@ OpenClaw can receive and send SMS through a Twilio phone number or Messaging Ser
4464}
4565```
466647-Env fallbacks for the default account:
48-`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` or `TWILIO_SMS_FROM` or `TWILIO_MESSAGING_SERVICE_SID`, and `SMS_PUBLIC_WEBHOOK_URL`.
67+Apply it:
68+69+```bash
70+openclaw config patch --file ./sms.patch.json5 --dry-run
71+openclaw config patch --file ./sms.patch.json5
72+```
49735074 </Step>
51755276 <Step title="Point Twilio at the Gateway webhook">
53-Set the Twilio Messaging webhook for incoming messages to:
77+In the Twilio phone number settings, open **Messaging** and set **A message comes in** to:
54785579```text
5680https://gateway.example.com/webhooks/sms
@@ -64,6 +88,11 @@ https://gateway.example.com/webhooks/sms
64886589```bash
6690openclaw gateway
91+```
92+93+Send a text message to the Twilio number. The first message creates a pairing request. Approve it:
94+95+```bash
6796openclaw pairing list sms
6897openclaw pairing approve sms <CODE>
6998```
@@ -73,47 +102,159 @@ openclaw pairing approve sms <CODE>
73102 </Step>
74103</Steps>
7510476-## Access control
105+## Configuration Examples
7710678-`channels.sms.dmPolicy` controls direct SMS access:
107+### Config file
7910880-- `pairing` (default)
81-- `allowlist` (requires at least one sender in `allowFrom`)
82-- `open` (requires `allowFrom` to include `"*"`)
83-- `disabled`
109+Use config-file setup when you want the channel definition to travel with the Gateway config:
8411085-`allowFrom` entries should be E.164 phone numbers such as `+15551234567`. `sms:` prefixes are accepted and normalized. For a private assistant, prefer `dmPolicy: "allowlist"` with explicit phone numbers.
111+```json5
112+{
113+ channels: {
114+ sms: {
115+ enabled: true,
116+ accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
117+ authToken: "twilio-auth-token",
118+ fromNumber: "+15551234567",
119+ publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
120+ dmPolicy: "pairing",
121+ },
122+ },
123+}
124+```
8612587-## Sending SMS
126+### Environment variables
8812789-Outbound SMS targets use the `sms:` service prefix with the SMS channel selected:
128+Use env setup for single-account deployments where secrets come from the host environment:
9012991130```bash
92-openclaw message send --channel sms --target sms:+15551234567 --message "hello"
131+export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
132+export TWILIO_AUTH_TOKEN="<twilio-auth-token>"
133+export TWILIO_PHONE_NUMBER="+15551234567"
134+export SMS_PUBLIC_WEBHOOK_URL="https://gateway.example.com/webhooks/sms"
93135```
9413695-When channel selection is implicit, `twilio-sms:+15551234567` selects this channel without taking over the existing channel-owned `sms:` service prefix used by iMessage.
137+Then enable the channel in config:
9613897-Agent replies from inbound SMS conversations automatically go back to the sender through the configured Twilio sender.
139+```json5
140+{
141+ channels: {
142+ sms: {
143+ enabled: true,
144+ dmPolicy: "pairing",
145+ },
146+ },
147+}
148+```
149+150+`TWILIO_SMS_FROM` is accepted as an alias for `TWILIO_PHONE_NUMBER`. Use `TWILIO_MESSAGING_SERVICE_SID` instead of a phone-number sender when Twilio should choose the sender from a Messaging Service.
151+152+### Allowlist-only private number
153+154+Use `allowlist` when only known phone numbers should be able to talk to the agent:
155+156+```json5
157+{
158+ channels: {
159+ sms: {
160+ enabled: true,
161+ accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
162+ authToken: "twilio-auth-token",
163+ fromNumber: "+15551234567",
164+ publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
165+ dmPolicy: "allowlist",
166+ allowFrom: ["+15557654321"],
167+ },
168+ },
169+}
170+```
9817199-Set `channels.sms.defaultTo` when operator-initiated sends should have a default phone number if no explicit target is provided.
172+### Messaging Service sender
100173101174Use `messagingServiceSid` instead of `fromNumber` when Twilio should choose the sender through a Messaging Service:
102175103176```json5
104177{
105178 channels: {
106179 sms: {
180+ enabled: true,
107181 accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
108182 authToken: "twilio-auth-token",
109183 messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
110184 publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
185+ dmPolicy: "pairing",
111186 },
112187 },
113188}
114189```
115190116-If both are present after defaults/env resolution, `fromNumber` is used.
191+If both `fromNumber` and `messagingServiceSid` are present after config and env resolution, `fromNumber` is used.
192+193+### Default outbound target
194+195+Set `defaultTo` when automation or agent-initiated delivery should have a default destination if a send flow omits an explicit target:
196+197+```json5
198+{
199+ channels: {
200+ sms: {
201+ enabled: true,
202+ accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
203+ authToken: "twilio-auth-token",
204+ fromNumber: "+15551234567",
205+ defaultTo: "+15557654321",
206+ publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
207+ },
208+ },
209+}
210+```
211+212+## Access control
213+214+`channels.sms.dmPolicy` controls direct SMS access:
215+216+- `pairing` (default)
217+- `allowlist` (requires at least one sender in `allowFrom`)
218+- `open` (requires `allowFrom` to include `"*"`)
219+- `disabled`
220+221+`allowFrom` entries should be E.164 phone numbers such as `+15551234567`. `sms:` prefixes are accepted and normalized. For a private assistant, prefer `dmPolicy: "allowlist"` with explicit phone numbers.
222+223+## Sending SMS
224+225+Outbound SMS targets use the `sms:` service prefix with the SMS channel selected:
226+227+```bash
228+openclaw message send --channel sms --target sms:+15551234567 --message "hello"
229+```
230+231+When channel selection is implicit, `twilio-sms:+15551234567` selects this channel without taking over the existing channel-owned `sms:` service prefix used by iMessage.
232+233+```bash
234+openclaw message send --target twilio-sms:+15551234567 --message "hello"
235+```
236+237+The CLI requires an explicit `--target`. `defaultTo` is for automation and agent-initiated delivery paths where the target can be resolved from channel config.
238+239+Agent replies from inbound SMS conversations automatically go back to the sender through the configured Twilio sender.
240+241+SMS output is plain text. OpenClaw strips markdown, flattens fenced code blocks, preserves readable links, and chunks long replies before sending them through Twilio.
242+243+## Verify Setup
244+245+After the Gateway starts:
246+247+1. Confirm the Gateway log shows the SMS webhook route.
248+2. Send an SMS to the Twilio number from your phone.
249+3. Run `openclaw pairing list sms`.
250+4. Approve the pairing code with `openclaw pairing approve sms <CODE>`.
251+5. Send another SMS and confirm the agent replies.
252+253+For outbound-only testing, use:
254+255+```bash
256+openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"
257+```
117258118259## Webhook security
119260@@ -159,3 +300,21 @@ Use `accounts` when you operate more than one Twilio number:
159300```
160301161302Each account should use a distinct `webhookPath`.
303+304+## Troubleshooting
305+306+### Twilio returns 403 or OpenClaw rejects the webhook
307+308+Check that `publicWebhookUrl` exactly matches the URL configured in Twilio, including scheme, host, path, and query string. Twilio signs the public URL string, so proxy rewrites and alternate hostnames can break signature validation.
309+310+### No pairing request appears
311+312+Check the Twilio number's **Messaging** webhook URL and method. It must point to the SMS webhook URL and use `POST`. Also confirm the Gateway is reachable from the public internet or through your tunnel.
313+314+### Outbound sends fail
315+316+Confirm `accountSid`, `authToken`, and either `fromNumber` or `messagingServiceSid` are resolved. If you use a trial Twilio account, the destination number may need to be verified in Twilio before outbound SMS will send.
317+318+### Messages arrive but the agent does not answer
319+320+Check `dmPolicy` and `allowFrom`. With the default `pairing` policy, the sender must be approved before normal agent turns are processed.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。