From f8c46df442fe7d2a2d2179436ea47e83227b3890 Mon Sep 17 00:00:00 2001
From: "openclaw-docs-sync[bot]"
 <openclaw-docs-sync[bot]@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:39:16 +0000
Subject: [PATCH] chore(sync): mirror docs from
 openclaw/openclaw@aaf4cc6862dd3657671ac606932f36d7f50f4322

---
 .openclaw-sync/source.json |  4 ++--
 docs/channels/slack.md     | 40 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index b9d8685c7..c404707a4 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "f0f1635f9f56e43edd852783145137de7c23559b",
-  "syncedAt": "2026-04-29T21:37:39.768Z"
+  "sha": "aaf4cc6862dd3657671ac606932f36d7f50f4322",
+  "syncedAt": "2026-04-29T21:37:50.600Z"
 }
diff --git a/docs/channels/slack.md b/docs/channels/slack.md
index e30ba8353..7ef96b71f 100644
--- a/docs/channels/slack.md
+++ b/docs/channels/slack.md
@@ -514,7 +514,7 @@ Current Slack message actions include `send`, `upload-file`, `download-file`, `r
     - `allowlist`
     - `disabled`
 
-    Channel allowlist lives under `channels.slack.channels` and should use stable channel IDs.
+    Channel allowlist lives under `channels.slack.channels` and **must use stable Slack channel IDs** (for example `C12345678`) as config keys.
 
     Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
 
@@ -524,6 +524,42 @@ Current Slack message actions include `send`, `upload-file`, `download-file`, `r
     - unresolved channel-name entries are kept as configured but ignored for routing by default
     - inbound authorization and channel routing are ID-first by default; direct username/slug matching requires `channels.slack.dangerouslyAllowNameMatching: true`
 
+    <Warning>
+    Name-based keys (`#channel-name` or `channel-name`) do **not** match under `groupPolicy: "allowlist"`. The channel lookup is ID-first by default, so a name-based key will never route successfully and all messages in that channel will be silently blocked. This differs from `groupPolicy: "open"`, where the channel key is not required for routing and a name-based key appears to work.
+
+    Always use the Slack channel ID as the key. To find it: right-click the channel in Slack → **Copy link** — the ID (`C...`) appears at the end of the URL.
+
+    Correct:
+
+    ```json5
+    {
+      channels: {
+        slack: {
+          groupPolicy: "allowlist",
+          channels: {
+            C12345678: { allow: true, requireMention: true },
+          },
+        },
+      },
+    }
+    ```
+
+    Incorrect (silently blocked under `groupPolicy: "allowlist"`):
+
+    ```json5
+    {
+      channels: {
+        slack: {
+          groupPolicy: "allowlist",
+          channels: {
+            "#eng-my-channel": { allow: true, requireMention: true },
+          },
+        },
+      },
+    }
+    ```
+    </Warning>
+
   </Tab>
 
   <Tab title="Mentions and channel users">
@@ -852,7 +888,7 @@ Primary reference: [Configuration reference - Slack](/gateway/config-channels#sl
     Check, in order:
 
     - `groupPolicy`
-    - channel allowlist (`channels.slack.channels`)
+    - channel allowlist (`channels.slack.channels`) — **keys must be channel IDs** (`C12345678`), not names (`#channel-name`). Name-based keys silently fail under `groupPolicy: "allowlist"` because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → **Copy link** — the `C...` value at the end of the URL is the channel ID.
     - `requireMention`
     - per-channel `users` allowlist