SMS Setup - Sean

What this page is

The practical native setup path.

Use

Use OpenClaw's bundled sms channel for new setups. It receives inbound SMS through a Gateway webhook and sends replies through Twilio's Messages API.

Native

Proof

Sean's own setup has the Twilio SMS webhook probe green on /webhooks/sms, with native outbound sending and native inbound replies verified end-to-end.

Live

Update

Start by running openclaw update, then openclaw doctor so config migrations and channel diagnostics run before Twilio is involved.

First step

Access

Default to pairing or allowlist. SMS costs money, phone numbers are personal data, and an open inbound number is a real control surface.

Restrict

Compliance

Have public terms, privacy, opt-in language, STOP/HELP handling, message frequency, and data-sharing language ready before carrier review.

Required

Setup path

The sequence that avoids most pain.

01

Update OpenClaw

Run the native implementation. Use openclaw update, then run openclaw doctor so config migrations and channel diagnostics happen before Twilio is involved.

openclaw updatedoctor

02

Prepare compliance pages

Publish your own privacy policy, terms, and opt-in page. Carrier review cares about voluntary consent, clear message purpose, STOP/HELP instructions, rates, frequency, and no marketing resale of mobile data.

PrivacyTermsConsent

03

Create a Twilio sender

Use an SMS-capable Twilio number or Messaging Service. Save the Account SID, Auth Token, sender number or Messaging Service SID, and finish the A2P 10DLC path if you are sending to US mobile numbers.

TwilioA2P 10DLC

04

Expose the webhook

Route a public HTTPS URL to the Gateway's SMS webhook path. The URL configured in OpenClaw and Twilio needs to match exactly, including scheme, host, path, and query string.

HTTPS/webhooks/sms

05

Configure the channel

Enable channels.sms with Twilio credentials, the public webhook URL, and a private sender policy. Prefer SecretRef or environment-backed secrets over plaintext config.

channels.smsSecretRef

06

Pair, probe, and test

Start the Gateway, run openclaw channels status --probe, send the first SMS, approve the pairing code, then test a second inbound and one outbound message. Check Twilio logs if no pairing request appears.

PairingProbeLogs

Config shape

Minimal native channel config.

Use the official docs for the exact current fields. The shape below is what to expect from the native channels.sms block.

{
  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"
    }
  }
}

Read official SMS docs Update guide

Compliance examples

Our public pages are examples, not legal templates.

Sean Alerts needed public compliance pages for SMS review. Copy the structure and checklist, not our legal identity or exact wording.

Privacy Policy

Discloses SMS data use, Twilio as transport provider, no sale of personal information, and no sharing mobile opt-in data for third-party marketing.

PrivacySMS data

Terms of Service

Documents program purpose, optional SMS consent, STOP/HELP, carrier delivery limits, rates, and non-emergency use.

TermsProgram rules

Consent Page

Public opt-in page with an unchecked-by-default consent box, clear disclosures, START instructions, and direct links to terms and privacy.

Opt-inConsent

Hard-won lesson: A2P review is not just "does the code send texts?" It is brand verification, campaign purpose, public policy pages, opt-in evidence, sample messages, and carrier expectations all matching each other.

Sharp edges

Things to get right before you blame the bot.

Exact webhook URL Twilio request signatures depend on the public URL string. Proxy rewrites, alternate domains, or path mismatches can make valid webhooks fail validation.

Sender access Use pairing or allowlist for personal agents. Treat every allowed phone number like a real user of your agent.

A2P consistency The site, Twilio campaign, sample messages, sender identity, and actual SMS behavior should all describe the same program.

Plain text output SMS is not Telegram. Keep responses short, assume no rich buttons, and expect markdown to be flattened.

Historical note Sean's SMS lane originally ran on a custom Twilio plugin; that work proved the path before OpenClaw shipped native channels.sms. If you see old plugin install instructions elsewhere, treat them as history, not setup guidance.

SMS receipts Original SMS RFC #85857 proposed Twilio-backed SMS as an official OpenClaw text channel. Merged follow-up #88601 fixed proof-discovered native SMS behavior. A2P docs PR #88743 captures the carrier-delivery lessons. SMS command auth PR #90998 tracks the current text-command fix. The maintainer native channel landed in #88476.

Textinga claw.More thana webhook.