openclaw channels CLI Reference: Accounts, Status & Logs

openclaw channels

This page covers managing chat channel accounts and their live status on the Gateway.

Additional references:

• Channel-specific guides: Channels
• Gateway setup details: 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

By default, channels list lists only chat channels: configured accounts, each tagged with installed, configured, and enabled status markers (use --json for machine-readable output). Adding --all reveals bundled channels lacking a configured account and installable catalog channels not yet present on disk. Provider authentication and usage details are handled elsewhere: openclaw models auth list covers provider auth profiles, while openclaw status or openclaw models list addresses usage and quota.

When you run --json, it pulls a local account inventory from plugin metadata, skipping any Gateway contact and bypassing channel setup or runtime execution. Accounts that are configured stay listed even if their plugin includes a setup entry. For live verification, turn to channels status --probe.

In an explicit multi-agent deployment, workspace-scoped channel plugins originate from agents.defaults.systemAgent.agentId. If that owner is absent, channels list returns the shared bundled, managed, and global inventory along with a diagnostic note; it never guesses a specific agent workspace.

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, max 30000), --json
• channels resolve <entries...>: --channel <name>, --account <id>, --agent <id>, --kind <auto|user|group|channel> (defaults to auto), --json
• channels logs: --channel <name|all> (defaults to all), --lines <n> (defaults to 200), --json

Patterns in channels logs --channel <name> match subsystem or module names anchored at <name> or gateway/channels/<name>, including slash-separated subpaths. Names that merely resemble these, like discord-archive, will not satisfy discord.

channels status --probe serves as the live path: on a reachable gateway, it executes per-account probeAccount and optional auditAccount checks, so the output may contain transport status along with probe results such as works, probe failed, audit ok, or audit failed. When the gateway is not reachable, channels status defaults to config-only summaries rather than live probe output.

Inbound dead letters

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

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 failure ages. JSON output additionally includes the retained payload, metadata, lane, and attempt timestamps for diagnostics.

Once the underlying issue is fixed, re-enqueue 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 access the same shared state database as the channel runtime. Resubmission retains the payload, metadata, and lane, but resets the attempt counter and queue age. It atomically replaces that event's failed marker, so repeating the command while the event is pending or claimed refuses instead of creating a second dispatch. The running channel picks it up on its next ingress drain. Completed events remain terminal and cannot be resubmitted. Failed rows created before payload retention was added can still appear in the list, but resubmission refuses them because their payload is unavailable.

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

Do not use openclaw sessions, Gateway sessions.list, or the agent sessions_list tool as a channel socket-health signal. Those surfaces report stored conversation rows, not provider runtime state. After a Discord provider restart, a connected but quiet account may be healthy while 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

For a headless host, complete non-interactive onboarding first, then add each channel with explicit credential flags or its environment-backed setup option:

export OPENAI_API_KEY="<provider-key>"
export TELEGRAM_BOT_TOKEN="<bot-token>"

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --skip-channels \
  --no-install-daemon
openclaw channels add --channel telegram --use-env

--use-env validates the environment variables declared by the selected channel plugin before writing config. For Telegram, the command requires TELEGRAM_BOT_TOKEN; other plugins name their missing variables in the error. The Gateway service must receive the same environment variables as the bootstrap shell. If the Gateway is already running with config reload enabled, it watches the config write and restarts the affected channel automatically.

See CLI automation for additional non-interactive provider and Gateway options. Container deployments should also follow the Docker headless bootstrap environment guidance.

Tip

openclaw channels add telegram --help or openclaw channels add --channel telegram --help shows only Telegram's setup flags. openclaw channels add --help shows only the shared command envelope.

channels remove only operates on installed/configured channel plugins. Use channels add first for installable catalog channels. Without --delete it asks to disable the account and keeps its config; --delete removes the config entries without prompting. For runtime-backed channel plugins, channels remove also asks the running Gateway to stop the selected account before it updates config, so disabling or deleting an account does not leave the old listener active until restart.

The shared control envelope contains only --channel, --account, and the optional account display --name. Each modern channel plugin owns its credential, transport, and provider-specific semantics. Once a channel is selected by positional id or --channel <id>, the CLI builds only that channel's options from bundled or installed plugin package metadata without loading channel runtime code.

Common-looking flags such as --token, --url, or --use-env are still channel-owned when a modern contract handles them. When a selected third-party plugin still uses the legacy shared setup adapter, 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 did not declare.

Examples of channel-owned flags include:

When a flag-driven add command requires the channel plugin to be installed, OpenClaw pulls from that channel's default install source and skips the interactive plugin installation prompt.

Flag-driven and guided setup both route through the chosen channel's parser, validation, account resolution, config writer, and post-write hooks. Flags that are not supported fail with the owning channel's setup error rather than being accepted via a global input bag.

Running openclaw channels add without any direct account, credential, or channel-config flags may trigger the interactive wizard. A positional channel id and --channel <id> both launch that channel's guided setup right away. Back returns to the full channel picker:

openclaw channels add telegram
openclaw channels add --channel telegram

An interactive terminal is mandatory for guided setup. In a non-TTY shell, OpenClaw exits immediately rather than waiting for input; use openclaw channels add --channel <id> --use-env or supply the selected plugin's credential flags.

The wizard may ask 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.

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

When a non-default account is added to a channel still using 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 supports --account <id> and --verbose; channels logout supports --account <id>.
• channels login and logout can infer the channel when only one configured channel supports that action; with several, pass --channel.
• channels logout prefers the live Gateway path when reachable, so logout stops any active listener before clearing channel auth state. If a local Gateway is not reachable, it falls back to local auth cleanup; with gateway.mode: "remote" the gateway error fails the command instead.
• Logout reports whether the plugin cleared saved auth. If the plugin reports that the account is not logged out, the CLI warns that other credentials may still be active; this is not a claim that provider-side tokens were revoked.
• Login and logout base config changes on the authored source, not runtime defaults. A logout with no credentials to clear does not rewrite config merely because runtime defaults were materialized; intentional plugin enablement or installation changes can still be saved.
• After a successful login, the CLI asks a reachable local Gateway to start the account; in remote mode it saves auth locally and notes that the remote runtime was not restarted.
• Run channels login from a terminal on the gateway host. Agent exec blocks this interactive login flow; channel-native agent login tools, such as whatsapp_login, should be used from chat when available.

Per-account recovery (non-destructive)

When an account needs to re-establish its connection while preserving its pairing and stored credentials, use the channels.stop and channels.start Gateway RPCs. Both expect operator.admin. Send them through openclaw gateway call:

# Stop one WhatsApp account without clearing its pairing.
openclaw gateway call channels.stop --params '{"channel":"whatsapp","accountId":"<accountId>"}'
# Start the same account again.
openclaw gateway call channels.start --params '{"channel":"whatsapp","accountId":"<accountId>"}'
openclaw channels status --channel whatsapp --probe

Pass the identical accountId to both calls. Leaving it out of both selects the default account.

channels.stop yields { channel, accountId, stopped }; channels.start yields { channel, accountId, started }. These booleans mirror the account's runtime state taken after the operation completes: started holds true only when running does, and stopped is true whenever running is false. A started: false reply alone does not prove the account is stopped, nor does started: true prove the provider link is sound. Inspect channel status and logs once recovery finishes.

This recovery path differs from openclaw channels logout, which wipes the account's credentials and forces a fresh login, and from openclaw gateway restart, which reboots the entire Gateway. For the crash-loop breaker and its manual channels.start override, refer to Restart recovery.

Troubleshooting

• Execute openclaw status --deep for a wide-ranging check.
• Turn to openclaw doctor when you want guided corrections.
• When the gateway is offline, openclaw channels status degrades to configuration-only summaries. If a supported channel credential is set through SecretRef but cannot be reached in the present command path, that account is listed as configured with degraded notes rather than as unconfigured.

Capabilities probe

Pull provider capability hints (intents or scopes where they exist) together with static feature support:

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

Notes:

• --channel is not required; drop it to enumerate every channel, including those supplied by plugins.
• --account works only in combination with --channel.
• --target takes channel:<id> or a plain numeric channel id, and it applies solely to Discord. For Discord voice channels, the permission check flags missing ViewChannel, Connect, Speak, SendMessages, and ReadMessageHistory.
• Probes vary 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 plus Graph roles/scopes (annotated where recognized). Channels lacking probes report Probe: unavailable.

Resolve names to IDs

Map channel and user names to IDs through 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"
openclaw channels --agent ops resolve --channel slack "#general"
openclaw channels resolve --agent ops --channel slack "#general"

Notes:

• In multi-agent setups, place --agent <id> in either parent or leaf position to pick the agent-owned workspace and channel plugin context.
• Apply --kind user|group|channel|auto to pin the target type.
• When multiple entries share a name, resolution favors active matches.
• channels resolve performs no writes. If a chosen account is configured via SecretRef but that credential is absent from the current command path, the command yields degraded unresolved results with notes instead of failing the whole run.
• channels resolve does not install channel plugins. Run channels add --channel <name> first to obtain an installable catalog channel before resolving names.

Related

• CLI reference
• Channels overview