mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-21 10:16:44 +00:00
docs: document channel ingress guarantees (#111069)
This commit is contained in:
Peter Steinberger
+23
-1
@@ -36,6 +36,12 @@ The wizard also asks for the API domain (Feishu vs Lark) and the group policy. I
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Inbound durability
|
||||
|
||||
OpenClaw durably queues authenticated `im.message.receive_v1` and `drive.notice.comment_add_v1` envelopes before agent dispatch. Pending or retryable events survive a Gateway restart, remain serialized per chat or document, and use Feishu's event ID to suppress duplicate queue entries while the active or retained completion record exists.
|
||||
|
||||
If a WebSocket event cannot be persisted after bounded retries, OpenClaw closes that socket and forces a fresh authenticated connection instead of continuing past an uncommitted turn. Other Feishu event types, including reactions and VC meeting invitations, use their normal event paths and do not receive this durable-queue guarantee.
|
||||
|
||||
## Access control
|
||||
|
||||
### Direct messages
|
||||
@@ -222,13 +228,24 @@ Feishu/Lark does not support native slash-command menus, so send these as plain
|
||||
7. Check logs: `openclaw logs --follow`
|
||||
|
||||
Subscribing to `vc.bot.meeting_invited_v1` only delivers the event. Automatic joins are
|
||||
default-off; enable them globally or for one account:
|
||||
default-off. To enable them globally:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
vcAutoJoin: true,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
To enable only one account, omit the top-level switch and set the account override:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
accounts: {
|
||||
meetings: { vcAutoJoin: true },
|
||||
},
|
||||
@@ -244,6 +261,10 @@ tool configured for app identity with the
|
||||
[`lark-cli` VC agent skill](https://github.com/larksuite/cli/tree/main/skills/lark-vc-agent)
|
||||
provides `vc +meeting-join`.
|
||||
|
||||
<Warning>
|
||||
The official `lark-cli` VC agent skill currently marks meeting-bot actions as a limited beta. If the tool returns `ErrNotInGray` or error code `20017`, the app or tenant has not been enabled for that beta; use the early-access guidance in the linked skill before troubleshooting ordinary scope grants.
|
||||
</Warning>
|
||||
|
||||
### QR setup does not react in the Feishu mobile app
|
||||
|
||||
1. Rerun setup: `openclaw channels login --channel feishu`
|
||||
@@ -628,6 +649,7 @@ Full configuration: [Gateway configuration](/gateway/configuration)
|
||||
| `channels.feishu.groupAllowFrom` | Group allowlist | - |
|
||||
| `channels.feishu.groupSenderAllowFrom` | Sender allowlist applied to all groups | - |
|
||||
| `channels.feishu.requireMention` | Require @mention in groups | `true` (`false` when policy `open`) |
|
||||
| `channels.feishu.allowBots` | Accept other bots that mention this bot, with bot-loop protection | `false` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Per-group @mention override; explicit IDs also admit the group in allowlist mode | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Enable/disable a specific group | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.allowFrom` | Per-group sender allowlist (overrides `groupSenderAllowFrom`) | - |
|
||||
|
||||
@@ -141,6 +141,12 @@ Configure the tunnel ingress rules to route only the webhook path:
|
||||
6. Group spaces require @-mention by default. Mentions are detected from Chat `USER_MENTION` annotations targeting the app; set `botUser` (e.g., `users/1234567890`) if detection needs the app's user resource name.
|
||||
7. When an exec or plugin approval starts from Google Chat and a stable `users/<id>` approver is configured, OpenClaw posts a native approval card (`cardsV2`) in the originating space or thread. Card buttons carry opaque callback tokens; the manual `/approve <id> <decision>` prompt appears only when native delivery is unavailable.
|
||||
|
||||
### Inbound durability
|
||||
|
||||
After request authentication, OpenClaw removes the add-on authorization object from storage and durably queues Google Chat `MESSAGE` events before returning `200`. A persistence failure returns `503`, allowing Google Chat to retry instead of acknowledging an event that could be lost.
|
||||
|
||||
Pending or retryable messages survive a Gateway restart, remain serialized per space, and use the Google Chat message resource name to suppress duplicate queue entries while the active or retained completion record exists. Non-message actions keep their existing detached webhook path and do not receive this durable-queue guarantee. Delivery remains at least once across the queue-to-agent boundary, so a crash during handoff can replay a turn.
|
||||
|
||||
## Targets
|
||||
|
||||
Use these identifiers for delivery and allowlists:
|
||||
|
||||
@@ -309,7 +309,15 @@ Quick mental model (evaluation order for group messages):
|
||||
|
||||
Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
|
||||
|
||||
Replying to a bot message counts as an implicit mention when the channel exposes reply metadata; quoting a bot message can also count on channels that expose quote metadata. Current built-in cases: Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp, and Zalo personal.
|
||||
Supported implicit mention facts are channel-specific:
|
||||
|
||||
| Fact | Current built-in producers |
|
||||
| --------------------- | ------------------------------------------------ |
|
||||
| Reply to the bot | Discord, Microsoft Teams, QQBot, Slack, Telegram |
|
||||
| Quote of the bot | WhatsApp, Zalo personal |
|
||||
| Bot joined the thread | Mattermost, Slack, Tlon |
|
||||
|
||||
Each fact defaults to enabled when the channel produces it. Set the corresponding `implicitMentions` flag to `false` to stop that fact from bypassing mention gating; native explicit mentions remain unaffected. A flag has no effect on channels that do not produce that fact.
|
||||
|
||||
```json5
|
||||
{
|
||||
|
||||
@@ -42,6 +42,12 @@ openclaw gateway run
|
||||
|
||||
Prefer a private IRC server for bot coordination. If you intentionally use a public IRC network, common choices include Libera.Chat, OFTC, and Snoonet. Avoid predictable public channels for bot or swarm backchannel traffic.
|
||||
|
||||
## Inbound durability
|
||||
|
||||
OpenClaw writes each accepted IRC `PRIVMSG` to its durable ingress queue before normal policy checks and agent dispatch. Pending or retryable messages survive a Gateway restart and remain serialized per channel or direct-message peer.
|
||||
|
||||
IRC does not provide a replayable delivery ID or resend messages missed by a disconnected client. OpenClaw therefore assigns a local ID that is stable only within the current TCP connection. The queue protects the local accept-to-dispatch window; it cannot recover a message that never reached OpenClaw or deduplicate a server resend across connections.
|
||||
|
||||
## Connection settings
|
||||
|
||||
| Key | Default | Notes |
|
||||
|
||||
@@ -48,6 +48,11 @@ agent processing continues asynchronously. Failed delivery is retried from the
|
||||
queue, including after a Gateway restart, and poison events become failed queue
|
||||
records after bounded retries. If durable persistence fails, the request returns
|
||||
`500` instead of acknowledging an event that could be lost.
|
||||
Delivery is at least once across the queue-to-agent boundary: a Gateway shutdown or
|
||||
crash during an active delivery can replay the turn. Message events deduplicate by
|
||||
LINE message ID; other event types use `webhookEventId`. Retained completion records
|
||||
suppress ordinary duplicate webhooks, but handlers that perform external side effects
|
||||
should still be idempotent.
|
||||
If you need a custom path, set `channels.line.webhookPath` or
|
||||
`channels.line.accounts.<id>.webhookPath` and update the URL accordingly.
|
||||
|
||||
|
||||
@@ -41,6 +41,12 @@ openclaw channels add --channel qqbot --token "AppID:AppSecret"
|
||||
|
||||
5. Restart the Gateway.
|
||||
|
||||
## Inbound durability
|
||||
|
||||
For QQ gateway turn events, OpenClaw persists the raw event before advancing the saved gateway resume sequence. Pending or retryable turns survive a Gateway restart, remain serialized per conversation, and use the provider event ID to suppress duplicate queue entries while the active or retained completion record exists.
|
||||
|
||||
If durable admission fails, OpenClaw terminates the current gateway socket without advancing the sequence. The reconnect/resume path can then request the uncommitted event again. Delivery is still at least once across the queue-to-agent boundary, so a crash during handoff can replay a turn.
|
||||
|
||||
Interactive setup:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -50,6 +50,12 @@ Webhook auth details:
|
||||
- Empty or missing tokens fail closed.
|
||||
- Payloads may be `application/x-www-form-urlencoded` or `application/json`; `token`, `user_id`, and `text` are required.
|
||||
|
||||
## Inbound durability
|
||||
|
||||
After token, sender-policy, and rate-limit checks pass, OpenClaw removes the webhook token from the stored envelope and durably queues the event before acknowledging it. The route returns `204` only after that append succeeds; a persistence failure returns `503` so Synology Chat can retry instead of silently losing the message.
|
||||
|
||||
Pending or retryable events survive a Gateway restart. Synology's stable `post_id` suppresses duplicate queue entries while the corresponding active or retained completion record exists. Delivery remains at least once across the queue-to-agent handoff, so a crash at that boundary can still replay a turn.
|
||||
|
||||
Minimal config:
|
||||
|
||||
```json5
|
||||
|
||||
@@ -58,6 +58,12 @@ Or edit config directly:
|
||||
Restart the gateway after editing config directly. Then DM the bot or @ mention it in a group
|
||||
channel.
|
||||
|
||||
## Inbound durability
|
||||
|
||||
OpenClaw persists accepted Tlon DM and group-chat events before agent dispatch. Pending or retryable turns survive a Gateway restart, and work remains serialized per group channel or direct peer. Stable Urbit message IDs also suppress a redelivered event while its queue record or retained completion record exists.
|
||||
|
||||
Delivery is at least once across the queue-to-agent boundary: a crash during handoff can replay a turn. Agent actions that produce external side effects should therefore remain idempotent where practical.
|
||||
|
||||
## Private/LAN ships
|
||||
|
||||
OpenClaw blocks private/internal hostnames and IP ranges for SSRF protection by default. If your
|
||||
|
||||
@@ -92,6 +92,12 @@ Minimal config:
|
||||
- `username` is the bot's account (who authenticates), `channel` is which chat room to join. One account entry joins exactly one channel.
|
||||
- Tokens work with or without the `oauth:` prefix; OpenClaw normalizes both ways (the setup wizard expects the `oauth:` form).
|
||||
|
||||
## Inbound durability
|
||||
|
||||
OpenClaw durably queues each accepted Twitch chat message before normal dispatch. Pending or retryable messages survive a Gateway restart, stay serialized for the configured channel, and use Twitch's message ID to suppress duplicate queue entries while the active or retained completion record exists.
|
||||
|
||||
Twitch chat does not replay a `PRIVMSG` after the client has accepted it. This protects the local accept-to-dispatch crash window, but it cannot recover messages missed before durable admission. If the queue append itself fails, OpenClaw logs the failure; reconnecting does not ask Twitch to resend that message.
|
||||
|
||||
## Token refresh (optional)
|
||||
|
||||
Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be refreshed by OpenClaw - regenerate when expired (they last a few hours; no app registration needed).
|
||||
|
||||
@@ -368,6 +368,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Route: /channels/feishu
|
||||
- Headings:
|
||||
- H2: Quick start
|
||||
- H2: Inbound durability
|
||||
- H2: Access control
|
||||
- H3: Direct messages
|
||||
- H3: Group chats
|
||||
@@ -424,6 +425,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H3: Option B: Reverse Proxy (Caddy)
|
||||
- H3: Option C: Cloudflare Tunnel
|
||||
- H2: How it works
|
||||
- H3: Inbound durability
|
||||
- H2: Targets
|
||||
- H2: Config highlights
|
||||
- H2: Troubleshooting
|
||||
@@ -517,6 +519,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Route: /channels/irc
|
||||
- Headings:
|
||||
- H2: Quick start
|
||||
- H2: Inbound durability
|
||||
- H2: Connection settings
|
||||
- H2: Security defaults
|
||||
- H2: Access control
|
||||
@@ -804,6 +807,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Headings:
|
||||
- H2: Install
|
||||
- H2: Setup
|
||||
- H2: Inbound durability
|
||||
- H2: Configure
|
||||
- H3: Streaming
|
||||
- H3: Access policy
|
||||
@@ -943,6 +947,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Headings:
|
||||
- H2: Install
|
||||
- H2: Quick setup
|
||||
- H2: Inbound durability
|
||||
- H2: Environment variables
|
||||
- H2: DM policy and access control
|
||||
- H2: Outbound delivery
|
||||
@@ -973,6 +978,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- Headings:
|
||||
- H2: Bundled plugin
|
||||
- H2: Setup
|
||||
- H2: Inbound durability
|
||||
- H2: Private/LAN ships
|
||||
- H2: Group channels
|
||||
- H2: Access control
|
||||
@@ -1018,6 +1024,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
|
||||
- H2: Install
|
||||
- H2: Quick setup
|
||||
- H2: What it is
|
||||
- H2: Inbound durability
|
||||
- H2: Token refresh (optional)
|
||||
- H2: Multi-account support
|
||||
- H2: Access control
|
||||
|
||||
@@ -103,7 +103,7 @@ Use `channels.defaults` for shared group-policy, implicit-mention, and heartbeat
|
||||
|
||||
- `channels.defaults.groupPolicy`: fallback group policy when a provider-level `groupPolicy` is unset.
|
||||
- `channels.defaults.contextVisibility`: default supplemental context visibility mode for all channels. Values: `all` (default, include all quoted/thread/history context), `allowlist` (only include context from allowlisted senders), `allowlist_quote` (same as allowlist but keep explicit quote/reply context). Per-channel override: `channels.<channel>.contextVisibility`.
|
||||
- `channels.defaults.implicitMentions`: controls which supported inbound facts count as mentions. `replyToBot`, `quotedBot`, and `threadParticipation` each default to `true`, preserving current behavior. Override per channel with `channels.<channel>.implicitMentions` or per account with `channels.<channel>.accounts.<id>.implicitMentions`; each flag resolves account -> channel -> defaults independently. The names are positive: set a flag to `false` to stop that fact from bypassing mention gating. Native explicit mentions are always allowed, and a flag has no effect when the channel does not produce that fact. These settings do not change outbound reply/thread modes or authorized command handling.
|
||||
- `channels.defaults.implicitMentions`: controls which supported inbound facts count as mentions. `replyToBot`, `quotedBot`, and `threadParticipation` each default to `true`, preserving current behavior. Override per channel with `channels.<channel>.implicitMentions` or per account with `channels.<channel>.accounts.<id>.implicitMentions`; each flag resolves account -> channel -> defaults independently. The names are positive: set a flag to `false` to stop that fact from bypassing mention gating. Native explicit mentions are always allowed, and a flag has no effect when the channel does not produce that fact. See [Mention gating](/channels/groups#mention-gating-default) for the current producer matrix. These settings do not change outbound reply/thread modes or authorized command handling.
|
||||
- `channels.defaults.heartbeat.showOk`: include healthy channel statuses in heartbeat output (default `false`).
|
||||
- `channels.defaults.heartbeat.showAlerts`: include degraded/error statuses in heartbeat output (default `true`).
|
||||
- `channels.defaults.heartbeat.useIndicator`: render compact indicator-style heartbeat output (default `true`).
|
||||
|
||||
Reference in New Issue
Block a user