diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 67c325ff5c4..3feb7462d3f 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -65,6 +65,30 @@ Use `channels.modelByChannel` to pin specific channel IDs to a model. Values acc } ``` +### Channel defaults and heartbeat + +Use `channels.defaults` for shared group-policy and heartbeat behavior across providers: + +```json5 +{ + channels: { + defaults: { + groupPolicy: "allowlist", // open | allowlist | disabled + heartbeat: { + showOk: false, + showAlerts: true, + useIndicator: true, + }, + }, + }, +} +``` + +- `channels.defaults.groupPolicy`: fallback group policy when a provider-level `groupPolicy` is unset. +- `channels.defaults.heartbeat.showOk`: include healthy channel statuses in heartbeat output. +- `channels.defaults.heartbeat.showAlerts`: include degraded/error statuses in heartbeat output. +- `channels.defaults.heartbeat.useIndicator`: render compact indicator-style heartbeat output. + ### WhatsApp WhatsApp runs through the gateway's web channel (Baileys Web). It starts automatically when a linked session exists. @@ -422,12 +446,20 @@ Mattermost ships as a plugin: `openclaw plugins install @openclaw/mattermost`. Chat modes: `oncall` (respond on @-mention, default), `onmessage` (every message), `onchar` (messages starting with trigger prefix). +- `channels.mattermost.configWrites`: allow or deny Mattermost-initiated config writes. +- `channels.mattermost.requireMention`: require `@mention` before replying in channels. + ### Signal ```json5 { channels: { signal: { + enabled: true, + account: "+15555550123", // optional account binding + dmPolicy: "pairing", + allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], + configWrites: true, reactionNotifications: "own", // off | own | all | allowlist reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], historyLimit: 50, @@ -438,6 +470,29 @@ Chat modes: `oncall` (respond on @-mention, default), `onmessage` (every message **Reaction notification modes:** `off`, `own` (default), `all`, `allowlist` (from `reactionAllowlist`). +- `channels.signal.account`: pin channel startup to a specific Signal account identity. +- `channels.signal.configWrites`: allow or deny Signal-initiated config writes. + +### BlueBubbles + +BlueBubbles is the recommended iMessage path (plugin-backed, configured under `channels.bluebubbles`). + +```json5 +{ + channels: { + bluebubbles: { + enabled: true, + dmPolicy: "pairing", + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles + }, + }, +} +``` + +- Core key paths covered here: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Full BlueBubbles channel configuration is documented in [BlueBubbles](/channels/bluebubbles). + ### iMessage OpenClaw spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required. @@ -469,6 +524,7 @@ OpenClaw spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required. - `cliPath` can point to an SSH wrapper; set `remoteHost` (`host` or `user@host`) for SCP attachment fetching. - `attachmentRoots` and `remoteAttachmentRoots` restrict inbound attachment paths (default: `/Users/*/Library/Messages/Attachments`). - SCP uses strict host-key checking, so ensure the relay host key already exists in `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: allow or deny iMessage-initiated config writes. @@ -479,6 +535,52 @@ exec ssh -T gateway-host imsg "$@" +### Microsoft Teams + +Microsoft Teams is extension-backed and configured under `channels.msteams`. + +```json5 +{ + channels: { + msteams: { + enabled: true, + configWrites: true, + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams + }, + }, +} +``` + +- Core key paths covered here: `channels.msteams`, `channels.msteams.configWrites`. +- Full Teams config (credentials, webhook, DM/group policy, per-team/per-channel overrides) is documented in [Microsoft Teams](/channels/msteams). + +### IRC + +IRC is extension-backed and configured under `channels.irc`. + +```json5 +{ + channels: { + irc: { + enabled: true, + dmPolicy: "pairing", + configWrites: true, + nickserv: { + enabled: true, + service: "NickServ", + password: "${IRC_NICKSERV_PASSWORD}", + register: false, + registerEmail: "bot@example.com", + }, + }, + }, +} +``` + +- Core key paths covered here: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Full IRC channel configuration (host/port/TLS/channels/allowlists/mention gating) is documented in [IRC](/channels/irc). + ### Multi-account (all channels) Run multiple accounts per channel (each with its own `accountId`): @@ -510,6 +612,11 @@ Run multiple accounts per channel (each with its own `accountId`): - Existing channel-only bindings (no `accountId`) keep matching the default account; account-scoped bindings remain optional. - `openclaw doctor --fix` also repairs mixed shapes by moving account-scoped top-level single-account values into `accounts.default` when named accounts exist but `default` is missing. +### Other extension channels + +Many extension channels are configured as `channels.` and documented in their dedicated channel pages (for example Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, and Twitch). +See the full channel index: [Channels](/channels). + ### Group chat mention gating Group messages default to **require mention** (metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats. @@ -1750,6 +1857,25 @@ OpenClaw uses the pi-coding-agent model catalog. Add custom providers via `model - Empty or missing agent `apiKey`/`baseUrl` fall back to `models.providers` in config. - Use `models.mode: "replace"` when you want config to fully rewrite `models.json`. +### Provider field details + +- `models.mode`: provider catalog behavior (`merge` or `replace`). +- `models.providers`: custom provider map keyed by provider id. +- `models.providers.*.api`: request adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc). +- `models.providers.*.apiKey`: provider credential (prefer SecretRef/env substitution). +- `models.providers.*.auth`: auth strategy (`api-key`, `token`, `oauth`, `aws-sdk`). +- `models.providers.*.authHeader`: force credential transport in the `Authorization` header when required. +- `models.providers.*.baseUrl`: upstream API base URL. +- `models.providers.*.headers`: extra static headers for proxy/tenant routing. +- `models.providers.*.models`: explicit provider model catalog entries. +- `models.bedrockDiscovery`: Bedrock auto-discovery settings root. +- `models.bedrockDiscovery.enabled`: turn discovery polling on/off. +- `models.bedrockDiscovery.region`: AWS region for discovery. +- `models.bedrockDiscovery.providerFilter`: optional provider-id filter for targeted discovery. +- `models.bedrockDiscovery.refreshInterval`: polling interval for discovery refresh. +- `models.bedrockDiscovery.defaultContextWindow`: fallback context window for discovered models. +- `models.bedrockDiscovery.defaultMaxTokens`: fallback max output tokens for discovered models. + ### Provider examples @@ -2027,6 +2153,13 @@ See [Local Models](/gateway/local-models). TL;DR: run MiniMax M2.1 via LM Studio - Loaded from `~/.openclaw/extensions`, `/.openclaw/extensions`, plus `plugins.load.paths`. - **Config changes require a gateway restart.** - `allow`: optional allowlist (only listed plugins load). `deny` wins. +- `plugins.entries..apiKey`: plugin-level API key convenience field (when supported by the plugin). +- `plugins.entries..env`: plugin-scoped env var map. +- `plugins.entries..config`: plugin-defined config object (validated by plugin schema). +- `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins. +- `plugins.installs`: CLI-managed install metadata used by `openclaw plugins update`. + - Includes `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Treat `plugins.installs.*` as managed state; prefer CLI commands over manual edits. See [Plugins](/tools/plugin). @@ -2149,11 +2282,11 @@ See [Plugins](/tools/plugin). - `port`: single multiplexed port for WS + HTTP. Precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (Tailscale IP only), or `custom`. - **Auth**: required by default. Non-loopback binds require a shared token/password. Onboarding wizard generates a token by default. -- `auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts. -- `auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). -- `auth.allowTailscale`: when `true`, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified via `tailscale whois`); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults to `true` when `tailscale.mode = "serve"`. -- `auth.rateLimit`: optional failed-auth limiter. Applies per client IP and per auth scope (shared-secret and device-token are tracked independently). Blocked attempts return `429` + `Retry-After`. - - `auth.rateLimit.exemptLoopback` defaults to `true`; set `false` when you intentionally want localhost traffic rate-limited too (for test setups or strict proxy deployments). +- `gateway.auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts. +- `gateway.auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)). +- `gateway.auth.allowTailscale`: when `true`, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified via `tailscale whois`); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults to `true` when `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: optional failed-auth limiter. Applies per client IP and per auth scope (shared-secret and device-token are tracked independently). Blocked attempts return `429` + `Retry-After`. + - `gateway.auth.rateLimit.exemptLoopback` defaults to `true`; set `false` when you intentionally want localhost traffic rate-limited too (for test setups or strict proxy deployments). - Browser-origin WS auth attempts are always throttled with loopback exemption disabled (defense-in-depth against browser-based localhost brute force). - `tailscale.mode`: `serve` (tailnet only, loopback bind) or `funnel` (public, requires auth). - `controlUi.allowedOrigins`: explicit browser-origin allowlist for Gateway WebSocket connects. Required when browser clients are expected from non-loopback origins. @@ -2599,7 +2732,7 @@ See [Cron Jobs](/automation/cron-jobs). ## Media model template variables -Template placeholders expanded in `tools.media.*.models[].args`: +Template placeholders expanded in `tools.media.models[].args`: | Variable | Description | | ------------------ | ------------------------------------------------- |