diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md
index 62084cfe0..080d3cb87 100644
--- a/docs/channels/imessage.md
+++ b/docs/channels/imessage.md
@@ -62,14 +62,17 @@ Disable with:
 - Automation permission when sending.
 - `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
 
-## Troubleshooting: macOS Privacy & Security (TCC)
+## Troubleshooting macOS Privacy and Security TCC
 
-If sending/receiving fails (for example, `imsg rpc` exits non-zero, or the gateway appears to hang), this is almost always a macOS permission prompt that was never approved.
+If sending/receiving fails (for example, `imsg rpc` exits non-zero, times out, or the gateway appears to hang), a common cause is a macOS permission prompt that was never approved.
+
+macOS grants TCC permissions per app/process context. Approve prompts in the same context that runs `imsg` (for example, Terminal/iTerm, a LaunchAgent session, or an SSH-launched process).
 
 Checklist:
 
 - **Full Disk Access**: allow access for the process running OpenClaw (and any shell/SSH wrapper that executes `imsg`). This is required to read the Messages database (`chat.db`).
 - **Automation → Messages**: allow the process running OpenClaw (and/or your terminal) to control **Messages.app** for outbound sends.
+- **`imsg` CLI health**: verify `imsg` is installed and supports RPC (`imsg rpc --help`).
 
 Tip: If OpenClaw is running headless (LaunchAgent/systemd/SSH) the macOS prompt can be easy to miss. Run a one-time interactive command in a GUI terminal to force the prompt, then retry:
 
@@ -79,7 +82,7 @@ imsg chats --limit 1
 imsg send <handle> "test"
 ```
 
-Related: if your workflow needs the agent to read local files from **Desktop/Documents/Downloads**, macOS may also gate those folders via TCC. If file reads/listings hang, grant the same process access (or move the file into the OpenClaw workspace).
+Related macOS folder permissions (Desktop/Documents/Downloads): [/platforms/mac/permissions](/platforms/mac/permissions).
 
 ## Setup (fast path)
 
@@ -100,7 +103,7 @@ If you want the bot to send from a **separate iMessage identity** (and keep your
 6. Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.
 7. Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.
 
-First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.
+First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry. See [Troubleshooting macOS Privacy and Security TCC](#troubleshooting-macos-privacy-and-security-tcc).
 
 Example wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:
 
diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md
index 929b0c776..8a6cdca90 100644
--- a/docs/channels/troubleshooting.md
+++ b/docs/channels/troubleshooting.md
@@ -1,5 +1,5 @@
 ---
-summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp)"
+summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp/iMessage)"
 read_when:
   - A channel connects but messages don’t flow
   - Investigating channel misconfiguration (intents, permissions, privacy mode)
@@ -22,6 +22,7 @@ openclaw channels status --probe
 - Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
 - Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
 - WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+- iMessage (legacy): [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
 
 ## Telegram quick fixes
 
diff --git a/docs/platforms/mac/permissions.md b/docs/platforms/mac/permissions.md
index 6f9cbfa19..12f75eb9f 100644
--- a/docs/platforms/mac/permissions.md
+++ b/docs/platforms/mac/permissions.md
@@ -40,5 +40,11 @@ sudo tccutil reset ScreenCapture bot.molt.mac
 sudo tccutil reset AppleEvents
 ```
 
+## Files and folders permissions (Desktop/Documents/Downloads)
+
+macOS may also gate Desktop, Documents, and Downloads for terminal/background processes. If file reads or directory listings hang, grant access to the same process context that performs file operations (for example Terminal/iTerm, LaunchAgent-launched app, or SSH process).
+
+Workaround: move files into the OpenClaw workspace (`~/.openclaw/workspace`) if you want to avoid per-folder grants.
+
 If you are testing permissions, always sign with a real certificate. Ad-hoc
 builds are only acceptable for quick local runs where permissions do not matter.