Channels

text

Copy

openclaw channels

Manage chat channel accounts and their runtime status on the Gateway.

Related docs:

• Channel guides: Channels
• Gateway configuration: Configuration

Common commands

bash
Copy
openclaw channels list
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

Status / capabilities / resolve / logs

• text

  Copy

  channels status
  :
  text

  Copy

  --probe
  ,
  text

  Copy

  --timeout <ms>
  ,
  text

  Copy

  --json
• text

  Copy

  channels capabilities
  :
  text

  Copy

  --channel <name>
  ,
  text

  Copy

  --account <id>
  (only with
  text

  Copy

  --channel
  ),
  text

  Copy

  --target <dest>
  ,
  text

  Copy

  --timeout <ms>
  ,
  text

  Copy

  --json
• text

  Copy

  channels resolve
  :
  text

  Copy

  <entries...>
  ,
  text

  Copy

  --channel <name>
  ,
  text

  Copy

  --account <id>
  ,
  text

  Copy

  --kind <auto|user|group>
  ,
  text

  Copy

  --json
• text

  Copy

  channels logs
  :
  text

  Copy

  --channel <name|all>
  ,
  text

  Copy

  --lines <n>
  ,
  text

  Copy

  --json

is the live path: on a reachable gateway it runs per-account and optional checks, so output can include transport state plus probe results such as , , , or . If the gateway is unreachable, falls back to config-only summaries instead of live probe output.

Add / remove accounts

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

Common non-interactive add surfaces include:

• bot-token channels:
  text

  Copy

  --token
  ,
  text

  Copy

  --bot-token
  ,
  text

  Copy

  --app-token
  ,
  text

  Copy

  --token-file
• Signal/iMessage transport fields:
  text

  Copy

  --signal-number
  ,
  text

  Copy

  --cli-path
  ,
  text

  Copy

  --http-url
  ,
  text

  Copy

  --http-host
  ,
  text

  Copy

  --http-port
  ,
  text

  Copy

  --db-path
  ,
  text

  Copy

  --service
  ,
  text

  Copy

  --region
• Google Chat fields:
  text

  Copy

  --webhook-path
  ,
  text

  Copy

  --webhook-url
  ,
  text

  Copy

  --audience-type
  ,
  text

  Copy

  --audience
• Matrix fields:
  text

  Copy

  --homeserver
  ,
  text

  Copy

  --user-id
  ,
  text

  Copy

  --access-token
  ,
  text

  Copy

  --password
  ,
  text

  Copy

  --device-name
  ,
  text

  Copy

  --initial-sync-limit
• Nostr fields:
  text

  Copy

  --private-key
  ,
  text

  Copy

  --relay-urls
• Tlon fields:
  text

  Copy

  --ship
  ,
  text

  Copy

  --url
  ,
  text

  Copy

  --code
  ,
  text

  Copy

  --group-channels
  ,
  text

  Copy

  --dm-allowlist
  ,
  text

  Copy

  --auto-discover-channels
• text

  Copy

  --use-env
  for default-account env-backed auth where supported

If a channel plugin needs to be installed during a flag-driven add command, OpenClaw uses the channel's default install source without opening the interactive plugin install prompt.

When you run

without flags, the interactive wizard can prompt:

• account ids per selected channel
• optional display names for those accounts
• text

  Copy

  Bind configured 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.

You can also manage the same routing rules later with

, , and (see agents).

When you add a non-default account to a channel that is still using single-account top-level settings, OpenClaw promotes account-scoped top-level values into the channel's account map before writing the new account. Most channels land those values in

, but bundled channels can preserve an existing matching promoted account instead. Matrix is the current example: if one named account already exists, or points at an existing named account, promotion preserves that account instead of creating a new .

Routing behavior stays consistent:

• Existing channel-only bindings (no
  text

  Copy

  accountId
  ) continue to match the default account.
• text

  Copy

  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

to move account-scoped values into the promoted account chosen for that channel. Most channels promote into ; Matrix can preserve an existing named/default target instead.

Login and logout (interactive)

bash
Copy
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp

• text

  Copy

  channels login
  supports
  text

  Copy

  --verbose
  .
• text

  Copy

  channels login
  and
  text

  Copy

  logout
  can infer the channel when only one supported login target is configured.
• Run
  text

  Copy

  channels login
  from a terminal on the gateway host. Agent
  text

  Copy

  exec
  blocks this interactive login flow; channel-native agent login tools, such as
  text

  Copy

  whatsapp_login
  , should be used from chat when available.

Troubleshooting

• Run
  text

  Copy

  openclaw status --deep
  for a broad probe.
• Use
  text

  Copy

  openclaw doctor
  for guided fixes.
• text

  Copy

  openclaw channels list
  prints
  text

  Copy

  Claude: HTTP 403 ... user:profile
  → usage snapshot needs the
  text

  Copy

  user:profile
  scope. Use
  text

  Copy

  --no-usage
  , or provide a claude.ai session key (
  text

  Copy

  CLAUDE_WEB_SESSION_KEY
  /
  text

  Copy

  CLAUDE_WEB_COOKIE
  ), or re-auth via Claude CLI.
• text

  Copy

  openclaw channels status
  falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.

Capabilities probe

Fetch provider capability hints (intents/scopes where available) plus static feature support:

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

Notes:

• text

  Copy

  --channel
  is optional; omit it to list every channel (including extensions).
• text

  Copy

  --account
  is only valid with
  text

  Copy

  --channel
  .
• text

  Copy

  --target
  accepts
  text

  Copy

  channel:<id>
  or a raw numeric channel id and only applies to Discord.
• Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; Microsoft Teams app token + Graph roles/scopes (annotated where known). Channels without probes report
  text

  Copy

  Probe: unavailable
  .

Resolve names to IDs

Resolve channel/user names to IDs using the provider directory:

bash
Copy
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
  text

  Copy

  --kind user|group|auto
  to force the target type.
• Resolution prefers active matches when multiple entries share the same name.
• text

  Copy

  channels resolve
  is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.

Related

• CLI reference
• Channels overview