openclaw channels¶

管理 Gateway 上的聊天频道账户及其运行状态。

相关文档：

• 频道指南：Channels
• 网关配置：Configuration

常用命令¶

openclaw channels list
openclaw channels list --all
openclaw channels status
openclaw channels status --probe
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 status 仍会保持已配置的频道可见。受影响的账户会报告 running: false、lifecycle: "blocked" 以及插件错误，而不是过期的探测成功结果。再次检查前，请运行 openclaw doctor，修复或更新插件，并重启 Gateway。

channels list 仅显示聊天频道：默认显示已配置的账户，每个账户带有 installed、configured 和 enabled 状态标签（使用 --json 获取机器可读输出）。传入 --all 可同时显示尚无已配置账户的捆绑频道，以及尚未安装到磁盘的可安装目录频道。提供商认证和模型用量信息位于其他命令中：openclaw models auth list 用于提供商认证配置文件，openclaw status 或 openclaw models list 用于用量/配额。

--json 会从插件元数据返回本地账户清单，不接触 Gateway，也不执行频道设置/运行时代码。即使已配置账户的插件具有设置条目，这些账户仍保持可见。如需实时检查，请使用 channels status --probe。

禁用插件不会卸载它。其频道在清单中仍保持 installed: true；使用 --all 时，未配置账户的已安装频道即使其插件被禁用，也会显示 origin: "available"。

在显式多智能体（multi-agent）设置中，工作区范围的频道插件来自 agents.defaults.systemAgent.agentId。如果没有该所有者，channels list 会返回共享的捆绑、托管和全局清单，并附上诊断信息；它不会猜测某个智能体工作区。

对于 add、login、logout、remove 和 resolve，或 capabilities --channel，请使用 --agent <id> 选择用于频道插件发现的工作区。该选项可在子命令之前或之后使用；子命令的值优先。若未指定，发现过程将使用配置的 System Agent 或现有的唯一/遗留所有者。在交互式引导的 channels add 中，如果没有此类所有者的显式 fleet，会在进行工作区范围的发现之前提示设置所有者；通过标志驱动或非交互式设置仍需要 --agent。选择工作区不会创建账户路由绑定；引导式设置会单独询问路由问题。

add、login、logout 和 remove 也接受 --account <id>。省略该选项时会选择默认账户。与死信（dead-letter）命令一样，空白值会被拒绝，而不是回退到默认账户，因此未设置的 shell 变量不会静默选择你未指定的账户。

使用 --json 时，每个频道条目都包含 label，以及其账户、安装状态和来源。当经过验证的官方频道元数据提供了有效的根相对文档路径时，条目还会包含 docsPath。自动化可以将此路径与 https://docs.openclaw.ai 拼接，而无需信任插件提供的 URL。未跟踪或不一致的已安装插件来源会省略 docsPath；可使用 openclaw doctor --fix 修复经过验证的遗留来源，或重新安装官方包。

状态 / 能力 / 解析 / 日志¶

capabilities 和 resolve 会拒绝显式为空或仅含空白的 --account 值。省略该选项以保留各命令的默认或更广泛的账户范围；不要传入空的 shell 变量来请求该范围。

• channels status：--channel <name>、--probe、--timeout <ms>（默认 60000）、--json
• channels capabilities：--channel <name>、--agent <id>、--account <id>（需要 --channel）、--target <dest>（需要 --channel）、--timeout <ms>（默认 10000，上限为 30000）、--json
• channels resolve <entries...>：--channel <name>、--account <id>、--agent <id>、--kind <auto|user|group|channel>（默认 auto）、--json
• channels logs：--channel <name|all>（默认 all）、--lines <n>（默认 200）、--json

channels logs --lines 要求正整数。省略 --lines 以使用默认值 200；显式为空的值会被拒绝。

channels logs --channel <name> 会匹配根位于 <name>、channels/<name> 或 gateway/channels/<name> 下的子系统或模块名称，包括以斜杠分隔的后代名称。类似名称（如 discord-archive）不会匹配 discord。

channels status --probe 是实时路径：在可访问的网关上，它会按账户运行 probeAccount 和可选的 auditAccount 检查，因此输出可以包含传输状态以及探测结果，例如 works、probe failed、audit ok 或 audit failed。如果网关不可访问，channels status 将回退到仅配置摘要，而不是实时探测输出。

如果 Gateway 返回错误（例如未知的 --channel），该命令会报告该错误并以非零状态退出，而不是显示不可访问的回退信息。

在探测频道之前，该命令会使用共享的就绪预算等待本地 Gateway 启动，并报告其观察到的阶段。截止时间到时启动仍在进行中属于非失败结果，而非网关不可访问。在这种情况下，--json 返回 { "status": "starting", "startupPhase": "…" }；请在启动完成后重新运行以收集频道结果。

该命令会读取现有的本地设备认证，而不会创建身份或持久化 Gateway 返回的令牌，包括在启用 --probe 时也是如此。

channels status 不支持 --deep；请使用 openclaw channels status --probe 进行频道检查。独立的顶层命令 openclaw status --deep 提供更广泛的状态探测。

入站死信¶

重试策略已用尽的入站事件会保留在共享状态数据库中，直到队列现有的失败条目保留期结束。使用以下命令检查某个频道账户：

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

文本视图显示事件 ID、失败原因、尝试次数和失败时长。JSON 输出还包含保留的载荷、元数据、lane 以及尝试时间戳，便于进行诊断。

省略 --account 时检查 default 账户。两个死信命令都会拒绝空值，而不是回退到 default，因此未设置的 shell 变量无法静默地选中你未指定的账户。你可以将 --account 放在 list 或 resubmit 之前或之后；位于叶命令之后的值优先生效。

修复根本问题后，使用原始事件 ID 重新入队一个事件：

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

请在 Gateway 主机上运行这些命令，以便它们与频道运行时访问相同的共享状态数据库。重新提交会保留载荷、元数据和 lane，但会重置尝试计数器和队列时长。它会原子性地替换该事件的失败标记，因此在事件处于待处理或已认领状态时重复执行该命令会被拒绝，而不会产生第二次派发。运行中的频道会在下一次入站排空时拾取该事件。已完成的事件保持终态，无法重新提交。在载荷保留功能添加之前创建的失败行仍可能出现在列表中，但重新提交会拒绝它们，因为其载荷不可用。

openclaw health 报告每个频道账户的死信数量和最早的失败时间。openclaw doctor 会指出受影响的账户，并指向检查命令。

不要将 openclaw sessions、Gateway 的 sessions.list 或代理的 sessions_list 工具用作频道 socket 健康信号。这些接口报告的是已存储的会话行，而非提供方运行时状态。在 Discord 提供方重启之后，已连接但静默的账户可能是健康的，而此时可能没有任何 Discord 会话行，直到下一个入站或出站会话事件出现。

添加 / 移除账户¶

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

对于无头主机，请先完成非交互式 onboarding 流程，然后使用显式凭据标志或其基于环境变量的设置选项添加每个频道：

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 会在写入配置前验证所选频道插件声明的环境变量。对于 Telegram，该命令需要 TELEGRAM_BOT_TOKEN；其他插件会在错误信息中指出缺失的变量。Gateway 服务必须接收与引导 shell 相同的环境变量。如果 Gateway 已在运行且启用了配置热重载，它会监视配置写入并自动重启受影响的频道。

更多非交互式提供方和 Gateway 选项，请参阅 CLI 自动化。容器部署还应遵循 Docker 无头引导 的环境指南。

channels remove 仅对已安装/已配置的频道插件生效。对于可安装的目录频道，请先使用 channels add。不带 --delete 时，它会询问是否禁用该账户并保留其配置；带 --delete 时则直接删除配置条目，不进行任何提示。

对于由运行时支撑的频道插件，channels remove 还会在更新配置前请求正在运行的 Gateway 停止所选账户，因此禁用或删除账户后，旧监听器不会一直保持活动直到重启。

共享控制外壳包含 --agent、--channel、--account 以及可选的账户显示名 --name。每个现代频道插件都拥有自己的凭据、传输层和提供方特定语义。一旦通过位置参数 id 或 --channel <id> 选定频道，CLI 只会根据内置或已安装的插件包元数据构建该频道的选项，而不会加载频道运行时代码。

当现代契约处理 --token、--url 或 --use-env 这类看似通用的标志时，它们仍然归频道所有。当所选第三方插件仍使用旧版共享设置适配器时，核心会仅针对该频道注册已发布的兼容标志集，以及其旧版 cliAddOptions。无关的旧版字段不会泄漏到其他频道，所选中的现代频道会拒绝其未声明的兼容标志。

频道自有标志的示例包括：

如果在基于标志的添加命令期间需要安装渠道插件，OpenClaw 会使用该渠道的默认安装源，而不会打开交互式插件安装提示。

引导式设置和基于标志的设置都会经过所选渠道的解析器、验证、账户解析、配置写入器和写入后钩子。不支持的标志会以所属渠道的设置错误失败，而不是通过全局输入袋被接受。

当你运行 openclaw channels add 且没有直接账户、凭据或渠道配置标志时，交互式向导可以提示。位置参数渠道 id 和 --channel <id> 都会立即打开该渠道的引导式设置。返回会回到完整的渠道选择器：

openclaw channels add telegram
openclaw channels add --channel telegram

引导式设置需要交互式终端。在非 TTY shell 中，OpenClaw 会立即退出，而不是等待输入。运行 openclaw channels add --channel <id> --help 可列出该渠道声明的设置标志，然后为非交互式设置传递这些标志。--use-env 只会在其已注册的地方出现：现代渠道会在其设置契约中声明对应字段，而仍使用旧版共享设置适配器的插件会从上述兼容集中获取它。当所选渠道不包含 --use-env 时，退出消息会指向该渠道的 --help，而不是 --use-env。

向导可以提示：

• 每个所选渠道的账户 id
• 这些账户的可选显示名称
• Route these channel accounts to agents now?

如果你确认现在绑定，向导会询问每个已配置的渠道账户应由哪个代理拥有，并写入账户范围的路由绑定。

你之后也可以使用 openclaw agents bindings、openclaw agents bind 和 openclaw agents unbind 管理相同的路由规则（参见 代理）。

当你向仍在使用单账户顶层设置的渠道添加非默认账户时，OpenClaw 会在写入新账户之前，将这些顶层值提升到该渠道的账户映射中。提升操作会在渠道恰好只有一个命名账户，或 defaultAccount 指向其中一个时，复用现有命名账户；否则这些值会落到 channels.<channel>.accounts.default。

路由行为保持一致：

• 现有仅渠道绑定（没有 accountId）会继续匹配默认账户。
• channels add 在非交互模式下不会自动创建或重写绑定。
• 交互式设置可以可选地添加账户范围的绑定。

如果你的配置已经处于混合状态（存在命名账户，且顶层单账户值仍被设置），请运行 openclaw doctor --fix，将账户范围的值移动到为该渠道选择的提升账户中。

登录和登出（交互式）¶

在 channels add 或 channels login 写入本地凭据或配置之前，OpenClaw 会将所选 CLI 状态/配置路径与本地 Gateway 或其已安装服务进行比较。已证实的不匹配会在写入前停止。远程 Gateway 或无法验证的已认证路径则会产生警告。

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

• channels login 支持 --agent <id>、--account <id> 和 --verbose；channels logout 支持 --agent <id> 和 --account <id>。
• channels login 和 logout 在只有一个已配置渠道支持该操作时可以推断渠道；如果有多个，请传递 --channel。只有省略 --channel 才会触发推断：空值会被拒绝，因此未设置的 shell 变量无法登出你未命名的渠道。
• channels logout 在可达时优先使用实时 Gateway 路径，因此登出会在清除渠道认证状态之前停止任何活动监听器。如果本地 Gateway 不可达，它会回退到本地认证清理；当 gateway.mode: "remote" 时，gateway 错误会使命令失败。
• 登出会报告插件是否清除了已保存的认证。如果插件报告账户未登出，CLI 会警告其他凭据可能仍然有效；这并不表示提供商侧 token 已被吊销。
• 登录和登出基于已编写的源进行配置更改，而不是运行时默认值。没有凭据可清除的登出不会仅仅因为运行时默认值被实例化就重写配置；有意的插件启用或安装更改仍可以保存。
• 成功登录后，CLI 会请求可达的本地 Gateway 启动该账户。如果该启动被跳过，或另一个生命周期操作拥有该账户，它会报告原因和一个状态命令；已保存的认证会保留。在远程模式下，它会在本地保存认证，并说明远程运行时未被重启。
• 请在 gateway 主机上的终端中运行 channels login。代理 exec 会阻止此交互式登录流程；当可用时，应从聊天中使用渠道原生的代理登录工具，例如 whatsapp_login。

按账户恢复（非破坏性）¶

当一个账户需要在保留其配对和凭据的情况下重新连接时，请调用 channels.stop 和 channels.start Gateway RPC。两者都需要 operator.admin。通过 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

在两次调用中使用相同的 accountId。从两者中省略它以选择默认账户。

channels.stop 返回 { channel, accountId, stopped }；channels.start 返回 { channel, accountId, started, outcome }。这些布尔值反映操作后账户的运行时快照：started 仅在 running 为 true 时为 true，stopped 在 running 不为 true 时为 true。started: false 响应本身并不能证明账户已停止，started: true 也不能证明提供商连接健康。恢复后，请检查频道状态和日志。

显式启动的账户会在 Gateway 拥有其生命周期时出现在运行时状态中，即使插件的静态账户列表尚未包含它。成功停止后，该未列出的账户会从状态中消失。默认账户选择以及自动健康监控和主机解冻恢复仍继续使用插件的静态账户列表。

主机解冻恢复会检测至少超出正常周期 45 秒的维护间隙。如果进程 CPU 时间消耗了至少一半的间隙，Gateway 会记录事件循环负载并跳过解冻恢复，以保留事件循环健康测量值。否则，它会刷新健康状态和在线状态，并在受跟踪的工作空闲时尝试频道恢复。繁忙检查保持工作准入开放。频道重启重试在解冻检测后十分钟过期，包括等待准入重新开放所花费的时间；延迟和放弃每次解冻各记录一次日志。此窗口过期后，普通频道健康监控继续。

outcome 说明生命周期所有者针对所请求账户做出的决定：

• { status: "handed-off" }：启动已移交给账户运行时。请检查状态以确认提供商连接。
• { status: "retry", reason }：现有任务、启动或停止仍拥有该账户（task-owned、start-in-flight 或 stop-in-flight）。正在运行的账户可能返回 task-owned 且 started: true；无需再次启动。在再次启动前，请等待进行中的停止完成。
• { status: "skipped", reason }：启动被跳过，例如因为账户处于 disabled、unconfigured 或 unlinked 状态。重试前，请修复所指定的账户状态。其他管理器原因包括 unsupported、autostart-suppressed、ambient-suppressed、secret-unavailable 和 manual-stop；手动 RPC 会绕过自动启动抑制，但不会绕过账户配置或密钥检查。

在频道或账户配置中显式禁用的账户会被跳过，而不会解析非活动凭据。对于已启用账户上不可用的已配置密钥，仍会返回 RPC 错误，而不是使用其他凭据启动。

与此恢复路径不同，openclaw channels logout 会清除账户凭据并要求重新登录；openclaw gateway restart 会重启整个 Gateway。有关崩溃循环断路器及其手动 channels.start 覆盖，请参阅 重启恢复。

故障排查¶

• 运行 openclaw status --deep 进行广泛探测。
• 使用 openclaw doctor 进行引导式修复。
• 当 Gateway 不可达时，openclaw channels status 会回退到仅配置摘要。如果受支持的频道凭据通过 SecretRef 配置，但在当前命令路径中不可用，它会报告该账户为已配置并附带降级说明，而不是显示为未配置。

能力探测¶

获取提供商能力提示（在可用时包括 intents/scopes）以及静态功能支持：

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

说明：

• --channel 是可选的；省略它以列出所有频道（包括插件提供的频道）。
• --account 仅在配合 --channel 时有效。
• 每个账户探测和诊断步骤都有各自的超时。停滞的步骤会在文本和 JSON 输出中报告，命令会继续处理其余账户。
• --target 接受 channel:<id> 或原始数字频道 ID，并且仅适用于 Discord。对于 Discord 语音频道，权限检查会标记缺失的 ViewChannel、Connect、Speak、SendMessages 和 ReadMessageHistory。
• 探测因提供商而异：Discord 机器人身份 + intents，外加可选的频道权限；Slack 机器人 + 用户 scopes；Telegram 机器人标志 + webhook；Signal 守护进程版本；Microsoft Teams 应用 token + Graph roles/scopes（在已知处标注）。没有探测的频道报告 Probe: unavailable。

将名称解析为 ID¶

使用提供商目录将频道/用户名称解析为 ID：

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"

说明：

• 在多智能体配置中，在父级或叶子位置使用 --agent <id> 以选择由智能体拥有的工作区和频道插件上下文。
• 使用 --kind user|group|channel|auto 强制指定目标类型。
• 当多个条目共享相同名称时，解析优先选择活动匹配项。
• channels resolve 是只读的。如果所选账户通过 SecretRef 配置，但该凭据在当前命令路径中不可用，命令会返回带有说明的降级未解析结果，而不是中止整个运行。
• channels resolve 不会安装频道插件。在为可安装的目录频道解析名称之前，请使用 channels add --channel <name>。

相关¶

• CLI 参考
• 频道概览