From 82c06e56043b26a10085b5eabd0804e9095037db Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Wed, 8 Apr 2026 00:56:22 -0400 Subject: [PATCH] Docs: clarify Slack streaming thread behavior Clarify the canonical Slack streaming config keys and legacy migration notes across the Slack docs and shared streaming concept docs. Document that native Slack streaming and assistant thread status require a reply thread, and call out the top-level DM fallback behavior. --- docs/channels/slack.md | 19 +++++--- docs/concepts/streaming.md | 5 ++- docs/gateway/configuration-reference.md | 59 ++++++++++++++++++++++--- 3 files changed, 67 insertions(+), 16 deletions(-) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index c42c56ab5da..b6c80257b68 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -463,9 +463,11 @@ Notes: - `block`: append chunked preview updates. - `progress`: show progress status text while generating, then send final text. -`channels.slack.nativeStreaming` controls Slack native text streaming when `streaming` is `partial` (default: `true`). +`channels.slack.streaming.nativeTransport` controls Slack native text streaming when `channels.slack.streaming.mode` is `partial` (default: `true`). -- A reply thread must be available for native text streaming to appear. Thread selection still follows `replyToMode`. Without one, the normal draft preview is used. +- A reply thread must be available for native text streaming and Slack assistant thread status to appear. Thread selection still follows `replyToMode`. +- Channel and group-chat roots can still use the normal draft preview when native streaming is unavailable. +- Top-level Slack DMs stay off-thread by default, so they do not show the thread-style preview; use thread replies or `typingReaction` if you want visible progress there. - Media and non-text payloads fall back to normal delivery. - If streaming fails mid-reply, OpenClaw falls back to normal delivery for remaining payloads. @@ -475,8 +477,10 @@ Use draft preview instead of Slack native text streaming: { channels: { slack: { - streaming: "partial", - nativeStreaming: false, + streaming: { + mode: "partial", + nativeTransport: false, + }, }, }, } @@ -484,8 +488,9 @@ Use draft preview instead of Slack native text streaming: Legacy keys: -- `channels.slack.streamMode` (`replace | status_final | append`) is auto-migrated to `channels.slack.streaming`. -- boolean `channels.slack.streaming` is auto-migrated to `channels.slack.nativeStreaming`. +- `channels.slack.streamMode` (`replace | status_final | append`) is auto-migrated to `channels.slack.streaming.mode`. +- boolean `channels.slack.streaming` is auto-migrated to `channels.slack.streaming.mode` and `channels.slack.streaming.nativeTransport`. +- legacy `channels.slack.nativeStreaming` is auto-migrated to `channels.slack.streaming.nativeTransport`. ## Typing reaction fallback @@ -687,7 +692,7 @@ Primary reference: - compatibility toggle: `dangerouslyAllowNameMatching` (break-glass; keep off unless needed) - channel access: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - - delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` + - delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` - ops/features: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## Troubleshooting diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md index 0653924d7dc..5711ffa85d5 100644 --- a/docs/concepts/streaming.md +++ b/docs/concepts/streaming.md @@ -126,13 +126,14 @@ Modes: Slack-only: -- `channels.slack.nativeStreaming` toggles Slack native streaming API calls when `streaming=partial` (default: `true`). +- `channels.slack.streaming.nativeTransport` toggles Slack native streaming API calls when `channels.slack.streaming.mode="partial"` (default: `true`). +- Slack native streaming and Slack assistant thread status require a reply thread target; top-level DMs do not show that thread-style preview. Legacy key migration: - Telegram: `streamMode` + boolean `streaming` auto-migrate to `streaming` enum. - Discord: `streamMode` + boolean `streaming` auto-migrate to `streaming` enum. -- Slack: `streamMode` auto-migrates to `streaming` enum; boolean `streaming` auto-migrates to `nativeStreaming`. +- Slack: `streamMode` auto-migrates to `streaming.mode`; boolean `streaming` auto-migrates to `streaming.mode` plus `streaming.nativeTransport`; legacy `nativeStreaming` auto-migrates to `streaming.nativeTransport`. ### Runtime behavior diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 0387c0eb883..5939a94cde5 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1,6 +1,6 @@ --- title: "Configuration Reference" -summary: "Complete reference for every OpenClaw config key, defaults, and channel settings" +summary: "Gateway config reference for core OpenClaw keys, defaults, and links to dedicated subsystem references" read_when: - You need exact field-level config semantics or defaults - You are validating channel, model, gateway, or tool config blocks @@ -8,7 +8,21 @@ read_when: # Configuration Reference -Every field available in `~/.openclaw/openclaw.json`. For a task-oriented overview, see [Configuration](/gateway/configuration). +Core config reference for `~/.openclaw/openclaw.json`. For a task-oriented overview, see [Configuration](/gateway/configuration). + +This page covers the main OpenClaw config surfaces and links out when a subsystem has its own deeper reference. It does **not** try to inline every channel/plugin-owned command catalog or every deep memory/QMD knob on one page. + +Code truth: + +- `openclaw config schema` prints the live JSON Schema used for validation and Control UI, with bundled/plugin/channel metadata merged in when available +- `config.schema.lookup` returns one path-scoped schema node for drill-down tooling +- `pnpm config:docs:check` / `pnpm config:docs:gen` validate the config-doc baseline hash against the current schema surface + +Dedicated deep references: + +- [Memory configuration reference](/reference/memory-config) for `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, and dreaming config under `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/tools/slash-commands) for the current built-in + bundled command catalog +- owning channel/plugin pages for channel-specific command surfaces Config format is **JSON5** (comments + trailing commas allowed). All fields are optional — OpenClaw uses safe defaults when omitted. @@ -426,8 +440,10 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: { + mode: "partial", // off | partial | block | progress + nativeTransport: true, // use Slack native streaming API when mode=partial + }, mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -452,13 +468,14 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat resolve the secret value. - `configWrites: false` blocks Slack-initiated config writes. - Optional `channels.slack.defaultAccount` overrides default account selection when it matches a configured account id. -- `channels.slack.streaming` is the canonical stream mode key. Legacy `streamMode` and boolean `streaming` values are auto-migrated. +- `channels.slack.streaming.mode` is the canonical Slack stream mode key. `channels.slack.streaming.nativeTransport` controls Slack's native streaming transport. Legacy `streamMode`, boolean `streaming`, and `nativeStreaming` values are auto-migrated. - Use `user:` (DM) or `channel:` for delivery targets. **Reaction notification modes:** `off`, `own` (default), `all`, `allowlist` (from `reactionAllowlist`). **Thread session isolation:** `thread.historyScope` is per-thread (default) or shared across channel. `thread.inheritParent` copies parent channel transcript to new threads. +- Slack native streaming plus the Slack assistant-style "is typing..." thread status require a reply thread target. Top-level DMs stay off-thread by default, so they use `typingReaction` or normal delivery instead of the thread-style preview. - `typingReaction` adds a temporary reaction to the inbound Slack message while a reply is running, then removes it on completion. Use a Slack emoji shortcode such as `"hourglass_flowing_sand"`. - `channels.slack.execApprovals`: Slack-native exec approval delivery and approver authorization. Same schema as Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack user IDs), `agentFilter`, `sessionFilter`, and `target` (`"dm"`, `"channel"`, or `"both"`). @@ -814,12 +831,18 @@ Include your own number in `allowFrom` to enable self-chat mode (ignores native { commands: { native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported text: true, // parse /commands in chat messages bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + restart: true, // allow /restart + gateway restart tool + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", // raw | hash + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -831,16 +854,32 @@ Include your own number in `allowFrom` to enable self-chat mode (ignores native +- This block configures command surfaces. For the current built-in + bundled command catalog, see [Slash Commands](/tools/slash-commands). +- This page is a **config-key reference**, not the full command catalog. Channel/plugin-owned commands such as QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, and Talk `/voice` are documented in their channel/plugin pages plus [Slash Commands](/tools/slash-commands). - Text commands must be **standalone** messages with leading `/`. - `native: "auto"` turns on native commands for Discord/Telegram, leaves Slack off. +- `nativeSkills: "auto"` turns on native skill commands for Discord/Telegram, leaves Slack off. - Override per channel: `channels.discord.commands.native` (bool or `"auto"`). `false` clears previously registered commands. +- Override native skill registration per channel with `channels..commands.nativeSkills`. - `channels.telegram.customCommands` adds extra Telegram bot menu entries. - `bash: true` enables `! ` for host shell. Requires `tools.elevated.enabled` and sender in `tools.elevated.allowFrom.`. - `config: true` enables `/config` (reads/writes `openclaw.json`). For gateway `chat.send` clients, persistent `/config set|unset` writes also require `operator.admin`; read-only `/config show` stays available to normal write-scoped operator clients. +- `mcp: true` enables `/mcp` for OpenClaw-managed MCP server config under `mcp.servers`. +- `plugins: true` enables `/plugins` for plugin discovery, install, and enable/disable controls. - `channels..configWrites` gates config mutations per channel (default: true). - For multi-account channels, `channels..accounts..configWrites` also gates writes that target that account (for example `/allowlist --config --account ` or `/config set channels..accounts....`). +- `restart: false` disables `/restart` and gateway restart tool actions. Default: `true`. +- `ownerAllowFrom` is the explicit owner allowlist for owner-only commands/tools. It is separate from `allowFrom`. +- `ownerDisplay: "hash"` hashes owner ids in the system prompt. Set `ownerDisplaySecret` to control hashing. - `allowFrom` is per-provider. When set, it is the **only** authorization source (channel allowlists/pairing and `useAccessGroups` are ignored). - `useAccessGroups: false` allows commands to bypass access-group policies when `allowFrom` is not set. +- Command docs map: + - built-in + bundled catalog: [Slash Commands](/tools/slash-commands) + - channel-specific command surfaces: [Channels](/channels) + - QQ Bot commands: [QQ Bot](/channels/qqbot) + - pairing commands: [Pairing](/channels/pairing) + - LINE card command: [LINE](/channels/line) + - memory dreaming: [Dreaming](/concepts/dreaming) @@ -1904,7 +1943,7 @@ Batches rapid text-only messages from the same sender into a single agent turn. } ``` -- `auto` controls auto-TTS. `/tts off|always|inbound|tagged` overrides per session. +- `auto` controls the default auto-TTS mode: `off`, `always`, `inbound`, or `tagged`. `/tts on|off` can override local prefs, and `/tts status` shows the effective state. - `summaryModel` overrides `agents.defaults.model.primary` for auto-summary. - `modelOverrides` is enabled by default; `modelOverrides.allowProvider` defaults to `false` (opt-in). - API keys fall back to `ELEVENLABS_API_KEY`/`XI_API_KEY` and `OPENAI_API_KEY`. @@ -2676,6 +2715,12 @@ See [Local Models](/gateway/local-models). TL;DR: run a large local model via LM - `enabled`: master dreaming switch (default `false`). - `frequency`: cron cadence for each full dreaming sweep (`"0 3 * * *"` by default). - phase policy and thresholds are implementation details (not user-facing config keys). +- Full memory config lives in [Memory configuration reference](/reference/memory-config): + - `agents.defaults.memorySearch.*` + - `memory.backend` + - `memory.citations` + - `memory.qmd.*` + - `plugins.entries.memory-core.config.dreaming` - Enabled Claude bundle plugins can also contribute embedded Pi defaults from `settings.json`; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches. - `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins. - `plugins.slots.contextEngine`: pick the active context engine plugin id; defaults to `"legacy"` unless you install and select another engine.