@captain-app/openclaw 2026.2.4

package/docs/channels/line.md

@@ -0,0 +1,186 @@
+---
+summary: "LINE Messaging API plugin setup, config, and usage"
+read_when:
+  - You want to connect OpenClaw to LINE
+  - You need LINE webhook + credential setup
+  - You want LINE-specific message options
+title: LINE
+---
+
+# LINE (plugin)
+
+LINE connects to OpenClaw via the LINE Messaging API. The plugin runs as a webhook
+receiver on the gateway and uses your channel access token + channel secret for
+authentication.
+
+Status: supported via plugin. Direct messages, group chats, media, locations, Flex
+messages, template messages, and quick replies are supported. Reactions and threads
+are not supported.
+
+## Plugin required
+
+Install the LINE plugin:
+
+```bash
+openclaw plugins install @openclaw/line
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+openclaw plugins install ./extensions/line
+```
+
+## Setup
+
+1. Create a LINE Developers account and open the Console:
+   https://developers.line.biz/console/
+2. Create (or pick) a Provider and add a **Messaging API** channel.
+3. Copy the **Channel access token** and **Channel secret** from the channel settings.
+4. Enable **Use webhook** in the Messaging API settings.
+5. Set the webhook URL to your gateway endpoint (HTTPS required):
+
+```
+https://gateway-host/line/webhook
+```
+
+The gateway responds to LINE’s webhook verification (GET) and inbound events (POST).
+If you need a custom path, set `channels.line.webhookPath` or
+`channels.line.accounts.<id>.webhookPath` and update the URL accordingly.
+
+## Configure
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    line: {
+      enabled: true,
+      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
+      channelSecret: "LINE_CHANNEL_SECRET",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+Env vars (default account only):
+
+- `LINE_CHANNEL_ACCESS_TOKEN`
+- `LINE_CHANNEL_SECRET`
+
+Token/secret files:
+
+```json5
+{
+  channels: {
+    line: {
+      tokenFile: "/path/to/line-token.txt",
+      secretFile: "/path/to/line-secret.txt",
+    },
+  },
+}
+```
+
+Multiple accounts:
+
+```json5
+{
+  channels: {
+    line: {
+      accounts: {
+        marketing: {
+          channelAccessToken: "...",
+          channelSecret: "...",
+          webhookPath: "/line/marketing",
+        },
+      },
+    },
+  },
+}
+```
+
+## Access control
+
+Direct messages default to pairing. Unknown senders get a pairing code and their
+messages are ignored until approved.
+
+```bash
+openclaw pairing list line
+openclaw pairing approve line <CODE>
+```
+
+Allowlists and policies:
+
+- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
+- `channels.line.allowFrom`: allowlisted LINE user IDs for DMs
+- `channels.line.groupPolicy`: `allowlist | open | disabled`
+- `channels.line.groupAllowFrom`: allowlisted LINE user IDs for groups
+- Per-group overrides: `channels.line.groups.<groupId>.allowFrom`
+
+LINE IDs are case-sensitive. Valid IDs look like:
+
+- User: `U` + 32 hex chars
+- Group: `C` + 32 hex chars
+- Room: `R` + 32 hex chars
+
+## Message behavior
+
+- Text is chunked at 5000 characters.
+- Markdown formatting is stripped; code blocks and tables are converted into Flex
+  cards when possible.
+- Streaming responses are buffered; LINE receives full chunks with a loading
+  animation while the agent works.
+- Media downloads are capped by `channels.line.mediaMaxMb` (default 10).
+
+## Channel data (rich messages)
+
+Use `channelData.line` to send quick replies, locations, Flex cards, or template
+messages.
+
+```json5
+{
+  text: "Here you go",
+  channelData: {
+    line: {
+      quickReplies: ["Status", "Help"],
+      location: {
+        title: "Office",
+        address: "123 Main St",
+        latitude: 35.681236,
+        longitude: 139.767125,
+      },
+      flexMessage: {
+        altText: "Status card",
+        contents: {
+          /* Flex payload */
+        },
+      },
+      templateMessage: {
+        type: "confirm",
+        text: "Proceed?",
+        confirmLabel: "Yes",
+        confirmData: "yes",
+        cancelLabel: "No",
+        cancelData: "no",
+      },
+    },
+  },
+}
+```
+
+The LINE plugin also ships a `/card` command for Flex message presets:
+
+```
+/card info "Welcome" "Thanks for joining!"
+```
+
+## Troubleshooting
+
+- **Webhook verification fails:** ensure the webhook URL is HTTPS and the
+  `channelSecret` matches the LINE console.
+- **No inbound events:** confirm the webhook path matches `channels.line.webhookPath`
+  and that the gateway is reachable from LINE.
+- **Media download errors:** raise `channels.line.mediaMaxMb` if media exceeds the
+  default limit.

package/docs/channels/location.md

@@ -0,0 +1,56 @@
+---
+summary: "Inbound channel location parsing (Telegram + WhatsApp) and context fields"
+read_when:
+  - Adding or modifying channel location parsing
+  - Using location context fields in agent prompts or tools
+title: "Channel Location Parsing"
+---
+
+# Channel location parsing
+
+OpenClaw normalizes shared locations from chat channels into:
+
+- human-readable text appended to the inbound body, and
+- structured fields in the auto-reply context payload.
+
+Currently supported:
+
+- **Telegram** (location pins + venues + live locations)
+- **WhatsApp** (locationMessage + liveLocationMessage)
+- **Matrix** (`m.location` with `geo_uri`)
+
+## Text formatting
+
+Locations are rendered as friendly lines without brackets:
+
+- Pin:
+  - `📍 48.858844, 2.294351 ±12m`
+- Named place:
+  - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
+- Live share:
+  - `🛰 Live location: 48.858844, 2.294351 ±12m`
+
+If the channel includes a caption/comment, it is appended on the next line:
+
+```
+📍 48.858844, 2.294351 ±12m
+Meet here
+```
+
+## Context fields
+
+When a location is present, these fields are added to `ctx`:
+
+- `LocationLat` (number)
+- `LocationLon` (number)
+- `LocationAccuracy` (number, meters; optional)
+- `LocationName` (string; optional)
+- `LocationAddress` (string; optional)
+- `LocationSource` (`pin | place | live`)
+- `LocationIsLive` (boolean)
+
+## Channel notes
+
+- **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
+- **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` are appended as the caption line.
+- **Matrix**: `geo_uri` is parsed as a pin location; altitude is ignored and `LocationIsLive` is always false.

package/docs/channels/matrix.md

@@ -0,0 +1,233 @@
+---
+summary: "Matrix support status, capabilities, and configuration"
+read_when:
+  - Working on Matrix channel features
+title: "Matrix"
+---
+
+# Matrix (plugin)
+
+Matrix is an open, decentralized messaging protocol. OpenClaw connects as a Matrix **user**
+on any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM
+the bot directly or invite it to rooms (Matrix "groups"). Beeper is a valid client option too,
+but it requires E2EE to be enabled.
+
+Status: supported via plugin (@vector-im/matrix-bot-sdk). Direct messages, rooms, threads, media, reactions,
+polls (send + poll-start as text), location, and E2EE (with crypto support).
+
+## Plugin required
+
+Matrix ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+
+```bash
+openclaw plugins install @openclaw/matrix
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+openclaw plugins install ./extensions/matrix
+```
+
+If you choose Matrix during configure/onboarding and a git checkout is detected,
+OpenClaw will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
+## Setup
+
+1. Install the Matrix plugin:
+   - From npm: `openclaw plugins install @openclaw/matrix`
+   - From a local checkout: `openclaw plugins install ./extensions/matrix`
+2. Create a Matrix account on a homeserver:
+   - Browse hosting options at [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)
+   - Or host it yourself.
+3. Get an access token for the bot account:
+   - Use the Matrix login API with `curl` at your home server:
+
+   ```bash
+   curl --request POST \
+     --url https://matrix.example.org/_matrix/client/v3/login \
+     --header 'Content-Type: application/json' \
+     --data '{
+     "type": "m.login.password",
+     "identifier": {
+       "type": "m.id.user",
+       "user": "your-user-name"
+     },
+     "password": "your-password"
+   }'
+   ```
+
+   - Replace `matrix.example.org` with your homeserver URL.
+   - Or set `channels.matrix.userId` + `channels.matrix.password`: OpenClaw calls the same
+     login endpoint, stores the access token in `~/.openclaw/credentials/matrix/credentials.json`,
+     and reuses it on next start.
+
+4. Configure credentials:
+   - Env: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_USER_ID` + `MATRIX_PASSWORD`)
+   - Or config: `channels.matrix.*`
+   - If both are set, config takes precedence.
+   - With access token: user ID is fetched automatically via `/whoami`.
+   - When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).
+5. Restart the gateway (or finish onboarding).
+6. Start a DM with the bot or invite it to a room from any Matrix client
+   (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE,
+   so set `channels.matrix.encryption: true` and verify the device.
+
+Minimal config (access token, user ID auto-fetched):
+
+```json5
+{
+  channels: {
+    matrix: {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_***",
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+E2EE config (end to end encryption enabled):
+
+```json5
+{
+  channels: {
+    matrix: {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "syt_***",
+      encryption: true,
+      dm: { policy: "pairing" },
+    },
+  },
+}
+```
+
+## Encryption (E2EE)
+
+End-to-end encryption is **supported** via the Rust crypto SDK.
+
+Enable with `channels.matrix.encryption: true`:
+
+- If the crypto module loads, encrypted rooms are decrypted automatically.
+- Outbound media is encrypted when sending to encrypted rooms.
+- On first connection, OpenClaw requests device verification from your other sessions.
+- Verify the device in another Matrix client (Element, etc.) to enable key sharing.
+- If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt;
+  OpenClaw logs a warning.
+- If you see missing crypto module errors (for example, `@matrix-org/matrix-sdk-crypto-nodejs-*`),
+  allow build scripts for `@matrix-org/matrix-sdk-crypto-nodejs` and run
+  `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` or fetch the binary with
+  `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.
+
+Crypto state is stored per account + access token in
+`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`
+(SQLite database). Sync state lives alongside it in `bot-storage.json`.
+If the access token (device) changes, a new store is created and the bot must be
+re-verified for encrypted rooms.
+
+**Device verification:**
+When E2EE is enabled, the bot will request verification from your other sessions on startup.
+Open Element (or another client) and approve the verification request to establish trust.
+Once verified, the bot can decrypt messages in encrypted rooms.
+
+## Routing model
+
+- Replies always go back to Matrix.
+- DMs share the agent's main session; rooms map to group sessions.
+
+## Access control (DMs)
+
+- Default: `channels.matrix.dm.policy = "pairing"`. Unknown senders get a pairing code.
+- Approve via:
+  - `openclaw pairing list matrix`
+  - `openclaw pairing approve matrix <CODE>`
+- Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
+- `channels.matrix.dm.allowFrom` accepts full Matrix user IDs (example: `@user:server`). The wizard resolves display names to user IDs when directory search finds a single exact match.
+
+## Rooms (groups)
+
+- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Allowlist rooms with `channels.matrix.groups` (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):
+
+```json5
+{
+  channels: {
+    matrix: {
+      groupPolicy: "allowlist",
+      groups: {
+        "!roomId:example.org": { allow: true },
+        "#alias:example.org": { allow: true },
+      },
+      groupAllowFrom: ["@owner:example.org"],
+    },
+  },
+}
+```
+
+- `requireMention: false` enables auto-reply in that room.
+- `groups."*"` can set defaults for mention gating across rooms.
+- `groupAllowFrom` restricts which senders can trigger the bot in rooms (full Matrix user IDs).
+- Per-room `users` allowlists can further restrict senders inside a specific room (use full Matrix user IDs).
+- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names only on an exact, unique match.
+- On startup, OpenClaw resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are ignored for allowlist matching.
+- Invites are auto-joined by default; control with `channels.matrix.autoJoin` and `channels.matrix.autoJoinAllowlist`.
+- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
+- Legacy key: `channels.matrix.rooms` (same shape as `groups`).
+
+## Threads
+
+- Reply threading is supported.
+- `channels.matrix.threadReplies` controls whether replies stay in threads:
+  - `off`, `inbound` (default), `always`
+- `channels.matrix.replyToMode` controls reply-to metadata when not replying in a thread:
+  - `off` (default), `first`, `all`
+
+## Capabilities
+
+| Feature         | Status                                                                                |
+| --------------- | ------------------------------------------------------------------------------------- |
+| Direct messages | ✅ Supported                                                                          |
+| Rooms           | ✅ Supported                                                                          |
+| Threads         | ✅ Supported                                                                          |
+| Media           | ✅ Supported                                                                          |
+| E2EE            | ✅ Supported (crypto module required)                                                 |
+| Reactions       | ✅ Supported (send/read via tools)                                                    |
+| Polls           | ✅ Send supported; inbound poll starts are converted to text (responses/ends ignored) |
+| Location        | ✅ Supported (geo URI; altitude ignored)                                              |
+| Native commands | ✅ Supported                                                                          |
+
+## Configuration reference (Matrix)
+
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+
+- `channels.matrix.enabled`: enable/disable channel startup.
+- `channels.matrix.homeserver`: homeserver URL.
+- `channels.matrix.userId`: Matrix user ID (optional with access token).
+- `channels.matrix.accessToken`: access token.
+- `channels.matrix.password`: password for login (token stored).
+- `channels.matrix.deviceName`: device display name.
+- `channels.matrix.encryption`: enable E2EE (default: false).
+- `channels.matrix.initialSyncLimit`: initial sync limit.
+- `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).
+- `channels.matrix.textChunkLimit`: outbound text chunk size (chars).
+- `channels.matrix.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
+- `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.matrix.dm.allowFrom`: DM allowlist (full Matrix user IDs). `open` requires `"*"`. The wizard resolves names to IDs when possible.
+- `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).
+- `channels.matrix.groupAllowFrom`: allowlisted senders for group messages (full Matrix user IDs).
+- `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.
+- `channels.matrix.groups`: group allowlist + per-room settings map.
+- `channels.matrix.rooms`: legacy group allowlist/config.
+- `channels.matrix.replyToMode`: reply-to mode for threads/tags.
+- `channels.matrix.mediaMaxMb`: inbound/outbound media cap (MB).
+- `channels.matrix.autoJoin`: invite handling (`always | allowlist | off`, default: always).
+- `channels.matrix.autoJoinAllowlist`: allowed room IDs/aliases for auto-join.
+- `channels.matrix.actions`: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).

package/docs/channels/mattermost.md

@@ -0,0 +1,138 @@
+---
+summary: "Mattermost bot setup and OpenClaw config"
+read_when:
+  - Setting up Mattermost
+  - Debugging Mattermost routing
+title: "Mattermost"
+---
+
+# Mattermost (plugin)
+
+Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported.
+Mattermost is a self-hostable team messaging platform; see the official site at
+[mattermost.com](https://mattermost.com) for product details and downloads.
+
+## Plugin required
+
+Mattermost ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+
+```bash
+openclaw plugins install @openclaw/mattermost
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+openclaw plugins install ./extensions/mattermost
+```
+
+If you choose Mattermost during configure/onboarding and a git checkout is detected,
+OpenClaw will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
+## Quick setup
+
+1. Install the Mattermost plugin.
+2. Create a Mattermost bot account and copy the **bot token**.
+3. Copy the Mattermost **base URL** (e.g., `https://chat.example.com`).
+4. Configure OpenClaw and start the gateway.
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      enabled: true,
+      botToken: "mm-token",
+      baseUrl: "https://chat.example.com",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## Environment variables (default account)
+
+Set these on the gateway host if you prefer env vars:
+
+- `MATTERMOST_BOT_TOKEN=...`
+- `MATTERMOST_URL=https://chat.example.com`
+
+Env vars apply only to the **default** account (`default`). Other accounts must use config values.
+
+## Chat modes
+
+Mattermost responds to DMs automatically. Channel behavior is controlled by `chatmode`:
+
+- `oncall` (default): respond only when @mentioned in channels.
+- `onmessage`: respond to every channel message.
+- `onchar`: respond when a message starts with a trigger prefix.
+
+Config example:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      chatmode: "onchar",
+      oncharPrefixes: [">", "!"],
+    },
+  },
+}
+```
+
+Notes:
+
+- `onchar` still responds to explicit @mentions.
+- `channels.mattermost.requireMention` is honored for legacy configs but `chatmode` is preferred.
+
+## Access control (DMs)
+
+- Default: `channels.mattermost.dmPolicy = "pairing"` (unknown senders get a pairing code).
+- Approve via:
+  - `openclaw pairing list mattermost`
+  - `openclaw pairing approve mattermost <CODE>`
+- Public DMs: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
+
+## Channels (groups)
+
+- Default: `channels.mattermost.groupPolicy = "allowlist"` (mention-gated).
+- Allowlist senders with `channels.mattermost.groupAllowFrom` (user IDs or `@username`).
+- Open channels: `channels.mattermost.groupPolicy="open"` (mention-gated).
+
+## Targets for outbound delivery
+
+Use these target formats with `openclaw message send` or cron/webhooks:
+
+- `channel:<id>` for a channel
+- `user:<id>` for a DM
+- `@username` for a DM (resolved via the Mattermost API)
+
+Bare IDs are treated as channels.
+
+## Multi-account
+
+Mattermost supports multiple accounts under `channels.mattermost.accounts`:
+
+```json5
+{
+  channels: {
+    mattermost: {
+      accounts: {
+        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
+        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
+      },
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+- No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set `chatmode: "onmessage"`.
+- Auth errors: check the bot token, base URL, and whether the account is enabled.
+- Multi-account issues: env vars only apply to the `default` account.