OpenClaw Channels CLI Reference – Accounts, Status, Capabilities

openclaw channels

Control chat channel accounts and their live status on the Gateway.

Related documentation:

• Channel guides: Channels
• Gateway configuration: Configuration

Common commands

openclaw channels list
openclaw channels list --all
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
openclaw channels dead-letters list --channel telegram --account default

channels list lists chat channels only: by default it shows configured accounts, each tagged with installed, configured, and enabled status indicators (--json in machine-readable mode). Supply --all to include bundled channels without a configured account and installable catalog channels not yet on disk. Provider authentication and model usage are handled elsewhere: use openclaw models auth list for provider auth profiles and openclaw status or openclaw models list for usage and quota information.

Status / capabilities / resolve / logs

• channels status: --channel <name>, --probe, --timeout <ms> (defaults to 10000), --json
• channels capabilities: --channel <name>, --account <id> (needs --channel), --target <dest> (needs --channel), --timeout <ms> (defaults to 10000, maximum 30000), --json
• channels resolve <entries...>: --channel <name>, --account <id>, --kind <auto|user|group> (defaults to auto), --json
• channels logs: --channel <name|all> (defaults to all), --lines <n> (defaults to 200), --json

channels status --probe is the live endpoint: against a reachable gateway it runs probeAccount per account and optionally auditAccount checks, so the output includes transport state together with probe results like works, probe failed, audit ok, or audit failed. When the gateway cannot be reached, channels status falls back to config-only summaries instead of live probe output.

Inbound dead letters

Inbound events that exhaust their retry policy stay in the shared state database for the queue's configured failed-entry retention period. To inspect a single channel account, run:

openclaw channels dead-letters list --channel telegram --account default
openclaw channels dead-letters list --channel telegram --account default --json

The text view displays event IDs, failure reasons, attempt counts, and how long ago each failure occurred. JSON output additionally includes the retained payload, metadata, lane, and attempt timestamps for diagnostic purposes.

After fixing the root cause, re-queue one event using its original event ID:

openclaw channels dead-letters resubmit <event-id> --channel telegram --account default

Execute these commands on the Gateway host so they connect to the same shared state database the channel runtime uses. Resubmission keeps the payload, metadata, and lane but resets the attempt counter and queue age. It atomically replaces that event's failed marker, so running the command again while the event is pending or claimed is refused rather than creating a duplicate dispatch. The running channel picks up the event on its next ingress drain. Completed events are terminal and cannot be resubmitted. Failed rows created before payload retention was added may still appear in the list, but resubmission rejects them because their payload is unavailable.

openclaw health reports dead-letter counts and the oldest failure age per channel account. openclaw doctor names the affected accounts and refers back to the inspection command.

Do not rely on openclaw sessions, Gateway sessions.list, or the agent sessions_list tool as a channel socket-health indicator. Those surfaces report stored conversation rows, not provider runtime state. After a Discord provider restart, a connected but idle account may be healthy even though no Discord session row appears until the next inbound or outbound conversation event.

Add / remove accounts

openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete

Tip

openclaw channels add telegram --help and openclaw channels add --channel telegram --help each display only the flags relevant to Telegram's setup. openclaw channels add --help shows just the shared command envelope.

The channels remove command works exclusively on channel plugins that are already installed or configured. For channels available in the catalog, run channels add first. When --delete is omitted, the tool asks to disable the account while preserving its configuration; --delete deletes those config entries with no further prompts.

For channel plugins backed by a runtime, channels remove also tells the running Gateway to stop the chosen account before updating the configuration. This ensures that disabling or removing an account does not leave the old listener active until the next restart.

The shared control envelope includes only --channel, --account, and the optional account display name --name. Each modern channel plugin manages its own credentials, transport layer, and provider-specific details. After a channel is selected by its positional id or --channel <id>, the CLI builds only that channel's options from bundled or installed plugin package metadata without loading the channel's runtime code.

Flags that look common, such as --token, --url, or --use-env, remain owned by the channel when a modern contract handles them. When the selected third-party plugin still relies on the legacy shared setup adapter, the core registers the released compatibility flag set for that channel only, alongside its legacy cliAddOptions. Unrelated legacy fields do not leak into other channels, and a modern selected channel rejects compatibility flags it never declared.

Below are examples of channel-owned flags:

When a channel plugin must be installed during a flag-driven add command, OpenClaw uses the channel's default install source and skips the interactive plugin install prompt.

Both guided and flag-driven setup pass through the selected channel's parser, validation, account resolution, config writer, and post-write hooks. Unsupported flags produce the owning channel's setup error rather than being accepted through a global input bag.

Running openclaw channels add without any direct account, credential, or channel-config flags opens the interactive wizard for prompts. A positional channel id and --channel <id> both preselect that channel without skipping guidance:

openclaw channels add telegram
openclaw channels add --channel telegram

The wizard can prompt for:

• account ids per selected channel
• optional display names for those accounts
• Route these channel accounts to agents now?

If you confirm bind now, the wizard asks which agent should own each configured channel account and writes account-scoped routing bindings.

These same routing rules can be managed later with openclaw agents bindings, openclaw agents bind, and openclaw agents unbind (see agents).

When you add a non-default account to a channel that still uses single-account top-level settings, OpenClaw promotes those top-level values into the channel's account map before writing the new account. Promotion reuses an existing named account when the channel has exactly one, or when defaultAccount points at one; otherwise the values land in channels.<channel>.accounts.default.

Routing behavior stays consistent:

• Existing channel-only bindings (no accountId) continue to match the default account.
• channels add does not auto-create or rewrite bindings in non-interactive mode.
• Interactive setup can optionally add account-scoped bindings.

If your config was already in a mixed state (named accounts present and top-level single-account values still set), run openclaw doctor --fix to move account-scoped values into the promoted account chosen for that channel.

Login and logout (interactive)

openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp

• channels login works with --account <id> and --verbose; channels logout handles --account <id>.
• When only one configured channel can perform a given action, channels login and logout detect it automatically. If multiple channels are available, supply --channel.
• channels logout attempts the live Gateway path first. If reachable, a logout stops any active listener before removing channel authentication state. When the local Gateway is unreachable, the command falls back to local credential cleanup. With gateway.mode: "remote" set, a gateway error causes the command to fail.
• Following a successful login, the CLI instructs an accessible local Gateway to start the account. In remote mode, it stores authentication locally and reports that the remote runtime was not restarted.
• Execute channels login on a terminal located on the gateway host. Agent exec prevents this interactive login flow. Instead, use channel-native agent login tools like whatsapp_login from chat when they are available.

Troubleshooting

• Run openclaw status --deep to perform a broad check.
• Use openclaw doctor for step-by-step corrections.
• openclaw channels status shows only configuration summaries when the gateway is not accessible. If a supported channel credential is defined through a SecretRef but cannot be retrieved in the current command context, the account is listed as configured with degraded notes rather than appearing as unconfigured.

Capabilities probe

Retrieve provider capability hints (intents or scopes where applicable) along with static feature support:

openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123

Notes:

• --channel is optional; leave it out to list every channel, including those from plugins.
• --account works only when combined with --channel.
• --target accepts channel:<id> or a plain numeric channel identifier and applies exclusively to Discord. For Discord voice channels, the permission check flags missing ViewChannel, Connect, Speak, SendMessages, and ReadMessageHistory.
• Probes differ by provider: Discord checks bot identity, intents, and optional channel permissions; Slack checks bot and user scopes; Telegram checks bot flags and webhook; Signal checks daemon version; Microsoft Teams checks app token and Graph roles or scopes (annotated where known). Channels without a probe return Probe: unavailable.

Resolve names to IDs

Convert channel and user names to IDs using the provider directory:

openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"

Notes:

• Use --kind user|group|auto to enforce the target type.
• When multiple entries share the same name, resolution prefers active matches.
• channels resolve is read-only. If a selected account is configured through a SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting entirely.
• channels resolve does not install channel plugins. For an installable catalog channel, run channels add --channel <name> before resolving names.

Related

• CLI reference
• Channels overview