vilvona 1.0.0

package/docs/channels/sms.md

@@ -0,0 +1,380 @@
+---
+summary: "Twilio SMS channel setup, access controls, and webhook configuration"
+read_when:
+  - You want to connect OpenClaw to SMS through Twilio
+  - You need SMS webhook or allowlist setup
+title: "SMS"
+---
+
+OpenClaw can receive and send SMS through a Twilio phone number or Messaging Service. The Gateway registers an inbound webhook route, validates Twilio request signatures by default, and sends replies back through Twilio's Messages API.
+
+<CardGroup cols={3}>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    Default DM policy for SMS is pairing.
+  </Card>
+  <Card title="Gateway security" icon="shield" href="/gateway/security">
+    Review webhook exposure and sender access controls.
+  </Card>
+  <Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
+    Cross-channel diagnostics and repair playbooks.
+  </Card>
+</CardGroup>
+
+## Before you begin
+
+You need:
+
+- A Twilio account with an SMS-capable phone number, or a Twilio Messaging Service.
+- The Twilio Account SID and Auth Token.
+- A public HTTPS URL that reaches your OpenClaw Gateway.
+- A sender policy choice: `pairing` for private use, `allowlist` for preapproved phone numbers, or `open` only for intentionally public SMS access.
+
+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.
+
+## Quick Setup
+
+<Steps>
+  <Step title="Create or choose a Twilio sender">
+    In Twilio, open **Phone Numbers > Manage > Active numbers** and choose an SMS-capable number. Save:
+
+    - Account SID, for example `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+    - Auth Token
+    - Sender phone number, for example `+15551234567`
+
+    If you use a Messaging Service instead of a fixed sender number, save the Messaging Service SID, for example `MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
+
+  </Step>
+
+  <Step title="Configure the SMS channel">
+
+Save this as `sms.patch.json5` and change the placeholders:
+
+```json5
+{
+  channels: {
+    sms: {
+      enabled: true,
+      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      authToken: "twilio-auth-token",
+      fromNumber: "+15551234567",
+      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+Apply it:
+
+```bash
+openclaw config patch --file ./sms.patch.json5 --dry-run
+openclaw config patch --file ./sms.patch.json5
+```
+
+  </Step>
+
+  <Step title="Point Twilio at the Gateway webhook">
+    In the Twilio phone number settings, open **Messaging** and set **A message comes in** to:
+
+```text
+https://gateway.example.com/webhooks/sms
+```
+
+    Use HTTP `POST`. The default local path is `/webhooks/sms`; change `channels.sms.webhookPath` if you need a different route.
+
+  </Step>
+
+  <Step title="Expose the exact SMS webhook path">
+    Your public URL must route the SMS path to the Gateway process. If you use Tailscale Funnel for local testing, expose `/webhooks/sms` explicitly:
+
+```bash
+tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/sms
+tailscale funnel status
+```
+
+    Voice Call and SMS use separate webhook paths. If the same Twilio number handles both, keep both routes configured in Twilio and in your tunnel.
+
+  </Step>
+
+  <Step title="Start the Gateway and approve first sender">
+
+```bash
+openclaw gateway
+```
+
+Send a text message to the Twilio number. The first message creates a pairing request. Approve it:
+
+```bash
+openclaw pairing list sms
+openclaw pairing approve sms <CODE>
+```
+
+    Pairing codes expire after 1 hour.
+
+  </Step>
+</Steps>
+
+## Configuration Examples
+
+### Config file
+
+Use config-file setup when you want the channel definition to travel with the Gateway config:
+
+```json5
+{
+  channels: {
+    sms: {
+      enabled: true,
+      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      authToken: "twilio-auth-token",
+      fromNumber: "+15551234567",
+      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+### Environment variables
+
+Use env setup for single-account deployments where secrets come from the host environment:
+
+```bash
+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"
+```
+
+Then enable the channel in config:
+
+```json5
+{
+  channels: {
+    sms: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+`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.
+
+### SecretRef auth token
+
+`authToken` can be a SecretRef. Use this when the Gateway should resolve the Twilio Auth Token from the OpenClaw secrets runtime instead of storing plaintext config:
+
+```json5
+{
+  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",
+    },
+  },
+}
+```
+
+The referenced environment variable or secret provider must be visible to the Gateway runtime. Restart managed Gateway processes after changing host environment variables.
+
+### Allowlist-only private number
+
+Use `allowlist` when only known phone numbers should be able to talk to the agent:
+
+```json5
+{
+  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 sender
+
+Use `messagingServiceSid` instead of `fromNumber` when Twilio should choose the sender through a Messaging Service:
+
+```json5
+{
+  channels: {
+    sms: {
+      enabled: true,
+      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      authToken: "twilio-auth-token",
+      messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+If both `fromNumber` and `messagingServiceSid` are present after config and env resolution, `fromNumber` is used.
+
+### Default outbound target
+
+Set `defaultTo` when automation or agent-initiated delivery should have a default destination if a send flow omits an explicit target:
+
+```json5
+{
+  channels: {
+    sms: {
+      enabled: true,
+      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      authToken: "twilio-auth-token",
+      fromNumber: "+15551234567",
+      defaultTo: "+15557654321",
+      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
+    },
+  },
+}
+```
+
+## Access control
+
+`channels.sms.dmPolicy` controls direct SMS access:
+
+- `pairing` (default)
+- `allowlist` (requires at least one sender in `allowFrom`)
+- `open` (requires `allowFrom` to include `"*"`)
+- `disabled`
+
+`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.
+
+## Sending SMS
+
+Outbound SMS targets use the `sms:` service prefix with the SMS channel selected:
+
+```bash
+openclaw message send --channel sms --target sms:+15551234567 --message "hello"
+```
+
+When channel selection is implicit, `twilio-sms:+15551234567` selects this channel without taking over the existing channel-owned `sms:` service prefix used by iMessage.
+
+```bash
+openclaw message send --target twilio-sms:+15551234567 --message "hello"
+```
+
+The CLI requires an explicit `--target`. `defaultTo` is for automation and agent-initiated delivery paths where the target can be resolved from channel config.
+
+Agent replies from inbound SMS conversations automatically go back to the sender through the configured Twilio sender.
+
+SMS output is plain text. OpenClaw strips markdown, flattens fenced code blocks, preserves readable links, and chunks long replies before sending them through Twilio.
+
+## Verify Setup
+
+After the Gateway starts:
+
+1. Confirm the Gateway log shows the SMS webhook route.
+2. Run a Twilio-side probe:
+
+```bash
+openclaw channels capabilities --channel sms
+openclaw channels status --channel sms --probe --json
+```
+
+3. Send an SMS to the Twilio number from your phone.
+4. Run `openclaw pairing list sms`.
+5. Approve the pairing code with `openclaw pairing approve sms <CODE>`.
+6. Send another SMS and confirm the agent replies.
+
+For outbound-only testing, use:
+
+```bash
+openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"
+```
+
+### End-to-end test from macOS iMessage/SMS
+
+On a Mac that can send carrier SMS through Messages, you can use `imsg` to drive the sender side without touching your phone:
+
+```bash
+imsg send --to "+15551234567" --service sms --text "OpenClaw SMS E2E $(date -u +%Y%m%dT%H%M%SZ)" --json
+openclaw pairing list sms
+openclaw pairing approve sms <CODE>
+imsg send --to "+15551234567" --service sms --text "reply exactly SMS pong" --json
+```
+
+The first message should create a pairing request. The second message should receive the agent reply through Twilio.
+
+## Webhook security
+
+By default, OpenClaw validates `X-Twilio-Signature` using `publicWebhookUrl` and `authToken`. Keep `publicWebhookUrl` byte-for-byte aligned with the URL configured in Twilio, including scheme, host, path, and query string.
+
+For local tunnel testing only, you can set:
+
+```json5
+{
+  channels: {
+    sms: {
+      dangerouslyDisableSignatureValidation: true,
+    },
+  },
+}
+```
+
+Do not use disabled signature validation on a public Gateway.
+
+## Multi-account config
+
+Use `accounts` when you operate more than one Twilio number:
+
+```json5
+{
+  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"],
+        },
+      },
+    },
+  },
+}
+```
+
+Each account should use a distinct `webhookPath`.
+
+## Troubleshooting
+
+### Twilio returns 403 or OpenClaw rejects the webhook
+
+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.
+
+### No pairing request appears
+
+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.
+
+If the Twilio message log shows error `11200`, Twilio accepted the inbound SMS but could not reach your webhook. Check:
+
+- Twilio **Messaging > A message comes in** points at `publicWebhookUrl`.
+- The method is `POST`.
+- The tunnel or reverse proxy exposes the exact `webhookPath`; for Tailscale Funnel, run `tailscale funnel status` and confirm `/webhooks/sms` is listed.
+- `publicWebhookUrl` uses the same scheme, host, path, and query string Twilio sends, so signature validation can reproduce the signed URL.
+
+### Outbound sends fail
+
+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.
+
+### Messages arrive but the agent does not answer
+
+Check `dmPolicy` and `allowFrom`. With the default `pairing` policy, the sender must be approved before normal agent turns are processed.

package/docs/channels/synology-chat.md

@@ -0,0 +1,187 @@
+---
+summary: "Synology Chat webhook setup and OpenClaw config"
+read_when:
+  - Setting up Synology Chat with OpenClaw
+  - Debugging Synology Chat webhook routing
+title: "Synology Chat"
+---
+
+Status: bundled plugin direct-message channel using Synology Chat webhooks.
+The plugin accepts inbound messages from Synology Chat outgoing webhooks and sends replies
+through a Synology Chat incoming webhook.
+
+## Bundled plugin
+
+Synology Chat ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Synology Chat,
+install it manually:
+
+Install from a local checkout:
+
+```bash
+openclaw plugins install ./path/to/local/synology-chat-plugin
+```
+
+Details: [Plugins](/tools/plugin)
+
+## Quick setup
+
+1. Ensure the Synology Chat plugin is available.
+   - Current packaged OpenClaw releases already bundle it.
+   - Older/custom installs can add it manually from a source checkout with the command above.
+   - `openclaw onboard` now shows Synology Chat in the same channel setup list as `openclaw channels add`.
+   - Non-interactive setup: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
+2. In Synology Chat integrations:
+   - Create an incoming webhook and copy its URL.
+   - Create an outgoing webhook with your secret token.
+3. Point the outgoing webhook URL to your OpenClaw gateway:
+   - `https://gateway-host/webhook/synology` by default.
+   - Or your custom `channels.synology-chat.webhookPath`.
+4. Finish setup in OpenClaw.
+   - Guided: `openclaw onboard`
+   - Direct: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
+5. Restart gateway and send a DM to the Synology Chat bot.
+
+Webhook auth details:
+
+- OpenClaw accepts the outgoing webhook token from `body.token`, then
+  `?token=...`, then headers.
+- Accepted header forms:
+  - `x-synology-token`
+  - `x-webhook-token`
+  - `x-openclaw-token`
+  - `Authorization: Bearer <token>`
+- Empty or missing tokens fail closed.
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    "synology-chat": {
+      enabled: true,
+      token: "synology-outgoing-token",
+      incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
+      webhookPath: "/webhook/synology",
+      dmPolicy: "allowlist",
+      allowedUserIds: ["123456"],
+      rateLimitPerMinute: 30,
+      allowInsecureSsl: false,
+    },
+  },
+}
+```
+
+## Environment variables
+
+For the default account, you can use env vars:
+
+- `SYNOLOGY_CHAT_TOKEN`
+- `SYNOLOGY_CHAT_INCOMING_URL`
+- `SYNOLOGY_NAS_HOST`
+- `SYNOLOGY_ALLOWED_USER_IDS` (comma-separated)
+- `SYNOLOGY_RATE_LIMIT`
+- `OPENCLAW_BOT_NAME`
+
+Config values override env vars.
+
+`SYNOLOGY_CHAT_INCOMING_URL` cannot be set from a workspace `.env`; see [Workspace `.env` files](/gateway/security).
+
+## DM policy and access control
+
+- `dmPolicy: "allowlist"` is the recommended default.
+- `allowedUserIds` accepts a list (or comma-separated string) of Synology user IDs.
+- In `allowlist` mode, an empty `allowedUserIds` list is treated as misconfiguration and the webhook route will not start (use `dmPolicy: "open"` with `allowedUserIds: ["*"]` for allow-all).
+- `dmPolicy: "open"` allows public DMs only when `allowedUserIds` includes `"*"`; with restrictive entries, only matching users can chat.
+- `dmPolicy: "disabled"` blocks DMs.
+- Reply recipient binding stays on stable numeric `user_id` by default. `channels.synology-chat.dangerouslyAllowNameMatching: true` is break-glass compatibility mode that re-enables mutable username/nickname lookup for reply delivery.
+- Pairing approvals work with:
+  - `openclaw pairing list synology-chat`
+  - `openclaw pairing approve synology-chat <CODE>`
+
+## Outbound delivery
+
+Use numeric Synology Chat user IDs as targets.
+
+Examples:
+
+```bash
+openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
+openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
+openclaw message send --channel synology-chat --target synology:123456 --text "Short prefix"
+```
+
+Media sends are supported by URL-based file delivery.
+Outbound file URLs must use `http` or `https`, and private or otherwise blocked network targets are rejected before OpenClaw forwards the URL to the NAS webhook.
+
+## Multi-account
+
+Multiple Synology Chat accounts are supported under `channels.synology-chat.accounts`.
+Each account can override token, incoming URL, webhook path, DM policy, and limits.
+Direct-message sessions are isolated per account and user, so the same numeric `user_id`
+on two different Synology accounts does not share transcript state.
+Give each enabled account a distinct `webhookPath`. OpenClaw now rejects duplicate exact paths
+and refuses to start named accounts that only inherit a shared webhook path in multi-account setups.
+If you intentionally need legacy inheritance for a named account, set
+`dangerouslyAllowInheritedWebhookPath: true` on that account or at `channels.synology-chat`,
+but duplicate exact paths are still rejected fail-closed. Prefer explicit per-account paths.
+
+```json5
+{
+  channels: {
+    "synology-chat": {
+      enabled: true,
+      accounts: {
+        default: {
+          token: "token-a",
+          incomingUrl: "https://nas-a.example.com/...token=...",
+        },
+        alerts: {
+          token: "token-b",
+          incomingUrl: "https://nas-b.example.com/...token=...",
+          webhookPath: "/webhook/synology-alerts",
+          dmPolicy: "allowlist",
+          allowedUserIds: ["987654"],
+        },
+      },
+    },
+  },
+}
+```
+
+## Security notes
+
+- Keep `token` secret and rotate it if leaked.
+- Keep `allowInsecureSsl: false` unless you explicitly trust a self-signed local NAS cert.
+- Inbound webhook requests are token-verified and rate-limited per sender.
+- Invalid token checks use constant-time secret comparison and fail closed.
+- Prefer `dmPolicy: "allowlist"` for production.
+- Keep `dangerouslyAllowNameMatching` off unless you explicitly need legacy username-based reply delivery.
+- Keep `dangerouslyAllowInheritedWebhookPath` off unless you explicitly accept shared-path routing risk in a multi-account setup.
+
+## Troubleshooting
+
+- `Missing required fields (token, user_id, text)`:
+  - the outgoing webhook payload is missing one of the required fields
+  - if Synology sends the token in headers, make sure the gateway/proxy preserves those headers
+- `Invalid token`:
+  - the outgoing webhook secret does not match `channels.synology-chat.token`
+  - the request is hitting the wrong account/webhook path
+  - a reverse proxy stripped the token header before the request reached OpenClaw
+- `Rate limit exceeded`:
+  - too many invalid token attempts from the same source can temporarily lock that source out
+  - authenticated senders also have a separate per-user message rate limit
+- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].`:
+  - `dmPolicy="allowlist"` is enabled but no users are configured
+- `User not authorized`:
+  - the sender's numeric `user_id` is not in `allowedUserIds`
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening