alvis
bedb527145
Some checks failed
ClawSweeper Dispatch / dispatch (push) Has been cancelled
CodeQL / Security High (actions) (push) Has been cancelled
CodeQL / Security High (channel-runtime-boundary) (push) Has been cancelled
CodeQL / Security High (core-auth-secrets) (push) Has been cancelled
CodeQL / Security High (mcp-process-tool-boundary) (push) Has been cancelled
CodeQL / Security High (network-ssrf-boundary) (push) Has been cancelled
CodeQL / Security High (plugin-trust-boundary) (push) Has been cancelled
CodeQL / Security High (process-exec-boundary) (push) Has been cancelled
Docs Sync Publish Repo / sync-publish-repo (push) Has been cancelled
Docs / docs (push) Has been cancelled
OpenClaw Stable Main Closeout / Resolve stable release closeout inputs (push) Has been cancelled
OpenClaw Stable Main Closeout / Verify stable main closeout (push) Has been cancelled
Workflow Sanity / no-tabs (push) Has been cancelled
Workflow Sanity / actionlint (push) Has been cancelled
Workflow Sanity / generated-doc-baselines (push) Has been cancelled
CI / runner-admission (push) Has been cancelled
CI / preflight (push) Has been cancelled
CI / security-fast (push) Has been cancelled
CI / pnpm-store-warmup (push) Has been cancelled
CI / build-artifacts (push) Has been cancelled
CI / native-i18n (push) Has been cancelled
CI / ${{ matrix.check_name }} (push) Has been cancelled
CI / ${{ matrix.checkName }} (push) Has been cancelled
CI / checks-node-compat-node22 (push) Has been cancelled
CI / check-bundled-channel-config-metadata (push) Has been cancelled
CI / check-dependencies (push) Has been cancelled
CI / check-guards (push) Has been cancelled
CI / check-lint (push) Has been cancelled
CI / check-prod-types (push) Has been cancelled
CI / check-shrinkwrap (push) Has been cancelled
CI / check-test-types (push) Has been cancelled
CI / check-additional-boundaries-a (push) Has been cancelled
CI / check-additional-boundaries-bcd (push) Has been cancelled
CI / check-additional-extension-bundled (push) Has been cancelled
CI / check-additional-extension-channels (push) Has been cancelled
CI / check-additional-extension-package-boundary (push) Has been cancelled
CI / check-additional-runtime-topology-architecture (push) Has been cancelled
CI / check-session-accessor-boundary (push) Has been cancelled
CI / check-session-transcript-reader-boundary (push) Has been cancelled
CI / check-docs (push) Has been cancelled
CI / skills-python (push) Has been cancelled
CI / macos-swift (push) Has been cancelled
CI / ios-build (push) Has been cancelled
CI / ci-timings-summary (push) Has been cancelled
Native App Locale Refresh / Refresh native fa (push) Has been cancelled
Native App Locale Refresh / Refresh native fr (push) Has been cancelled
Native App Locale Refresh / Refresh native hi (push) Has been cancelled
Native App Locale Refresh / Refresh native id (push) Has been cancelled
Native App Locale Refresh / Refresh native it (push) Has been cancelled
Native App Locale Refresh / Refresh native ja-JP (push) Has been cancelled
Control UI Locale Refresh / plan (push) Has been cancelled
Control UI Locale Refresh / Refresh ${{ matrix.locale }} (push) Has been cancelled
Control UI Locale Refresh / Commit control UI locale refresh (push) Has been cancelled
Live Media Runner Image / Build live media runner image (push) Has been cancelled
Native App Locale Refresh / Refresh native ar (push) Has been cancelled
Native App Locale Refresh / Refresh native de (push) Has been cancelled
Native App Locale Refresh / Refresh native es (push) Has been cancelled
Native App Locale Refresh / Refresh native ko (push) Has been cancelled
Native App Locale Refresh / Refresh native nl (push) Has been cancelled
Native App Locale Refresh / Refresh native pl (push) Has been cancelled
Native App Locale Refresh / Refresh native pt-BR (push) Has been cancelled
Native App Locale Refresh / Refresh native ru (push) Has been cancelled
Native App Locale Refresh / Refresh native sv (push) Has been cancelled
Native App Locale Refresh / Refresh native th (push) Has been cancelled
Native App Locale Refresh / Refresh native tr (push) Has been cancelled
Native App Locale Refresh / Refresh native uk (push) Has been cancelled
Native App Locale Refresh / Refresh native vi (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-CN (push) Has been cancelled
Native App Locale Refresh / Refresh native zh-TW (push) Has been cancelled
Native App Locale Refresh / Commit native locale refresh (push) Has been cancelled
Plugin Init Scaffold Validation / Validate provider scaffold (push) Has been cancelled
Plugin NPM Release / preview_plugins_npm (push) Has been cancelled
Plugin NPM Release / Validate release publish approval (push) Has been cancelled
Plugin NPM Release / preview_plugin_pack (push) Has been cancelled
Plugin NPM Release / publish_plugins_npm (push) Has been cancelled
Sandbox Common Smoke / sandbox-common-smoke (push) Has been cancelled
Website Installer Sync / static (push) Has been cancelled
Website Installer Sync / linux-docker (push) Has been cancelled
Website Installer Sync / macos-installer (push) Has been cancelled
Website Installer Sync / windows-installer (push) Has been cancelled
Website Installer Sync / sync-website (push) Has been cancelled
Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11), free to diverge. Tree copied sans upstream .git; upstream remote added for future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19. Preserves docs/ARCHITECTURE.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2
160 lines
13 KiB
Markdown
160 lines
13 KiB
Markdown
---
|
|
summary: "Fast channel level troubleshooting with per channel failure signatures and fixes"
|
|
read_when:
|
|
- Channel transport says connected but replies fail
|
|
- You need channel specific checks before deep provider docs
|
|
title: "Channel troubleshooting"
|
|
---
|
|
|
|
Use this page when a channel connects but behavior is wrong.
|
|
|
|
## Command ladder
|
|
|
|
Run these in order first:
|
|
|
|
```bash
|
|
openclaw status
|
|
openclaw gateway status
|
|
openclaw logs --follow
|
|
openclaw doctor
|
|
openclaw channels status --probe
|
|
```
|
|
|
|
Healthy baseline:
|
|
|
|
- `Runtime: running`
|
|
- `Connectivity probe: ok`
|
|
- `Capability: read-only`, `write-capable`, or `admin-capable`
|
|
- Channel probe shows transport connected and, where supported, `works` or `audit ok`
|
|
|
|
## After an update
|
|
|
|
Use this when Telegram, iMessage, BlueBubbles-era configs, or another plugin channel disappears
|
|
after updating.
|
|
|
|
```bash
|
|
openclaw status --all
|
|
openclaw doctor --fix
|
|
openclaw gateway restart
|
|
openclaw status --all
|
|
```
|
|
|
|
Look for `plugin load failed: dependency tree corrupted; run openclaw doctor --fix` in `openclaw
|
|
status --all`. That means the channel is configured, but plugin setup/load hit a corrupted
|
|
dependency tree instead of registering the channel. `openclaw doctor --fix` clears stale
|
|
plugin-runtime dependency symlinks and stale auth shadows, then `openclaw gateway restart` reloads
|
|
clean state.
|
|
|
|
## WhatsApp
|
|
|
|
### WhatsApp failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ----------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Connected but no DM replies | `openclaw pairing list whatsapp` | Approve sender or switch DM policy/allowlist. |
|
|
| Group messages ignored | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
|
|
| QR login times out with 408 | Check gateway `HTTPS_PROXY` / `HTTP_PROXY` env | Set a reachable proxy; use `NO_PROXY` only for bypasses. |
|
|
| Random disconnect/relogin loops | `openclaw channels status --probe` + logs | Recent reconnects are flagged even when currently connected; watch logs, restart the gateway, then relink if flapping continues. |
|
|
| `status=408 Request Time-out` loop | Probe, logs, doctor, then gateway status | Fix host connectivity/timing first; back up auth and re-link the account if the loop persists. |
|
|
| Replies arrive seconds/minutes late | `openclaw doctor --fix` | Doctor stops verified stale local TUI clients when they are degrading the Gateway event loop. |
|
|
|
|
Full troubleshooting: [WhatsApp troubleshooting](/channels/whatsapp#troubleshooting)
|
|
|
|
## Telegram
|
|
|
|
### Telegram failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
|
| `/start` but no usable reply flow | `openclaw pairing list telegram` | Approve pairing or change DM policy. |
|
|
| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. |
|
|
| Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. |
|
|
| Startup reports `getMe returned 401` | Check configured token source | Re-copy or regenerate the BotFather token and update `botToken`, `tokenFile`, or default-account `TELEGRAM_BOT_TOKEN`. |
|
|
| Polling stalls or reconnects slowly | `openclaw logs --follow` for polling diagnostics | Upgrade; if restarts are false positives, tune `pollingStallThresholdMs`. Persistent stalls still point to proxy/DNS/IPv6. |
|
|
| `setMyCommands` rejected at startup | Inspect logs for `BOT_COMMANDS_TOO_MUCH` | Reduce plugin/skill/custom Telegram commands or disable native menus. |
|
|
| Upgraded and allowlist blocks you | `openclaw security audit` and config allowlists | Run `openclaw doctor --fix` or replace `@username` with numeric sender IDs. |
|
|
|
|
Full troubleshooting: [Telegram troubleshooting](/channels/telegram#troubleshooting)
|
|
|
|
## Discord
|
|
|
|
### Discord failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Bot online but no guild replies | `openclaw channels status --probe` | Allow guild/channel and verify message content intent. |
|
|
| Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
|
|
| Typing/token usage but no Discord message | Check whether this is an ambient room event or an opted-in `message_tool` room where the model missed `message(action=send)` | Inspect the gateway verbose log for suppressed final payload metadata, verify `messages.groupChat.unmentionedInbound`, read [Ambient room events](/channels/ambient-room-events), or keep `messages.groupChat.visibleReplies: "automatic"` for normal group requests. |
|
|
| DM replies missing | `openclaw pairing list discord` | Approve DM pairing or adjust DM policy. |
|
|
|
|
Full troubleshooting: [Discord troubleshooting](/channels/discord#troubleshooting)
|
|
|
|
## Slack
|
|
|
|
### Slack failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Socket mode connected but no responses | `openclaw channels status --probe` | Verify app token + bot token and required scopes; watch for `botTokenStatus` / `appTokenStatus = configured_unavailable` on SecretRef-backed setups. |
|
|
| DMs blocked | `openclaw pairing list slack` | Approve pairing or relax DM policy. |
|
|
| Channel message ignored | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`. |
|
|
|
|
Full troubleshooting: [Slack troubleshooting](/channels/slack#troubleshooting)
|
|
|
|
## iMessage
|
|
|
|
### iMessage failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
| `imsg` missing or fails on non-macOS | `openclaw channels status --probe --channel imessage` | Run OpenClaw on the Messages Mac or use an SSH wrapper for `cliPath`. |
|
|
| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation | Re-grant TCC permissions and restart channel process. |
|
|
| DM sender blocked | `openclaw pairing list imessage` | Approve pairing or update allowlist. |
|
|
|
|
Full troubleshooting: [iMessage troubleshooting](/channels/imessage#troubleshooting)
|
|
|
|
## Signal
|
|
|
|
### Signal failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
|
|
| Daemon reachable but bot silent | `openclaw channels status --probe` | Verify `signal-cli` daemon URL/account and receive mode. |
|
|
| DM blocked | `openclaw pairing list signal` | Approve sender or adjust DM policy. |
|
|
| Group replies do not trigger | Check group allowlist and mention patterns | Add sender/group or loosen gating. |
|
|
|
|
Full troubleshooting: [Signal troubleshooting](/channels/signal#troubleshooting)
|
|
|
|
## QQ Bot
|
|
|
|
### QQ Bot failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
|
|
| Bot replies "gone to Mars" | Verify `appId` and `clientSecret` in config | Set credentials or restart the gateway. |
|
|
| No inbound messages | `openclaw channels status --probe` | Verify credentials on the QQ Open Platform. |
|
|
| Voice not transcribed | Check STT provider config | Configure `channels.qqbot.stt` or `tools.media.audio`. |
|
|
| Proactive messages not arriving | Check QQ platform interaction requirements | QQ may block bot-initiated messages without recent interaction. |
|
|
|
|
Full troubleshooting: [QQ Bot troubleshooting](/channels/qqbot#troubleshooting)
|
|
|
|
## Matrix
|
|
|
|
### Matrix failure signatures
|
|
|
|
| Symptom | Fastest check | Fix |
|
|
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
|
|
| Logged in but ignores room messages | `openclaw channels status --probe` | Check `groupPolicy`, room allowlist, and mention gating. |
|
|
| DMs do not process | `openclaw pairing list matrix` | Approve sender or adjust DM policy. |
|
|
| Encrypted rooms fail | `openclaw matrix verify status` | Re-verify the device, then check `openclaw matrix verify backup status`. |
|
|
| Backup restore is pending/broken | `openclaw matrix verify backup status` | Run `openclaw matrix verify backup restore` or rerun with a recovery key. |
|
|
| Cross-signing/bootstrap looks wrong | `openclaw matrix verify bootstrap` | Repair secret storage, cross-signing, and backup state in one pass. |
|
|
|
|
Full setup and config: [Matrix](/channels/matrix)
|
|
|
|
## Related
|
|
|
|
- [Pairing](/channels/pairing)
|
|
- [Channel routing](/channels/channel-routing)
|
|
- [Gateway troubleshooting](/gateway/troubleshooting)
|