跳转至

openclaw channels

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

相关文档:

常见命令

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"。

在显式多智能体配置中,工作区范围的频道插件来自 agents.defaults.systemAgent.agentId。如果没有该所有者,channels list 会返回共享的内置、托管和全局清单,并附带诊断信息; 它不会猜测某个智能体工作区。

对于 add、login、logout、remove 和 resolve,或 capabilities --channel, 使用 --agent <id> 来选择用于频道插件发现的工作区。 该选项可放在子命令之前或之后;子命令中的值优先。 如果没有该选项,发现过程会使用已配置的 System Agent 或现有的唯一/旧版所有者。 在交互式引导式 channels add 中,显式集群如果没有这样的所有者, 会在工作区范围发现之前提示输入设置所有者;基于标志或 非交互式设置仍需要 --agent。选择工作区不会 创建账户路由绑定;引导式设置会单独询问路由。

add、login、logout 和 remove 也接受 --account <id>。省略时选择 默认账户。空白值会被拒绝,而不是回退到默认值,这与 死信命令相同,因此未设置的 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 读取 Gateway 记录的频道生命周期和健康事实, 以及不含密钥的账户元数据。它不会解析操作凭据或 运行实时状态钩子。未知配置和过期连接仍会保持可见; 频道未记录的提供商详细信息可能需要显式探测。 WhatsApp 记录的认证年龄会随频道心跳刷新。

channels status --probe 是实时路径:在可到达的 Gateway 上,它会按账户 运行 probeAccount 和可选的 auditAccount 检查,因此输出可以包含传输 状态,以及成功或失败的账户检查和审计。频道会并发检查, 每个频道有有界截止时间,包括账户解析和 状态钩子。超时的频道会返回其记录状态并附带警告,而不是 阻止健康频道返回其结果。 如果 Gateway 不可达,channels status 会回退到仅配置摘要, 而不是实时检查输出。

如果 Gateway 返回错误,例如未知的 --channel,命令 会报告该错误并以非零状态退出,而不是显示不可达回退。

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

该命令读取现有的本地设备身份验证,而不会创建身份或持久化 Gateway 返回的 Token 值,包括启用 --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 输出还包含保留的负载、元数据、泳道和尝试时间戳,用于诊断。

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

在修复根本问题后,使用其原始事件 ID 重新入队一个事件:

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

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

openclaw health 报告每个通道账户的死信数量和最久失败时长。openclaw doctor 列出受影响的账户,并指回检查命令。

不要将 openclaw sessions、Gateway 的 sessions.list 或代理的 sessions_list 工具用作通道套接字健康信号。这些界面报告的是存储的会话行,而不是提供商运行时状态。在 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

对于无头主机,先完成非交互式引导,然后使用显式凭据标志或其基于环境的设置选项添加每个通道:

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 无头引导 环境指南。

Tip

openclaw channels add telegram --help 或 openclaw channels add --channel telegram --help 仅显示 Telegram 的设置标志。openclaw channels add --help 仅显示共享命令外壳。

channels remove 仅操作已安装/已配置的通道插件。对于可安装的目录通道,请先使用 channels add。如果不使用 --delete,它会询问是否禁用账户并保留其配置;--delete 会删除配置条目而不提示。 对于运行时支持的通道插件,channels remove 还会要求正在运行的 Gateway 在更新配置之前停止所选账户,因此禁用或删除账户不会让旧监听器保持活动直到重启。

共享控制外壳包含 --agent、--channel、--account 以及可选的账户显示 --name。每个现代通道插件拥有其凭据、传输和特定于提供商的语义。一旦通过位置 ID 或 --channel <id> 选择通道,CLI 仅从捆绑或已安装的插件包元数据中构建该通道的选项,而不加载通道运行时代码。

诸如 --token、--url 或 --use-env 等常见标志,当由现代契约处理时,仍属于通道所有。当所选的第三方插件仍使用旧版共享设置适配器时,核心仅为该通道注册已发布的兼容标志集,与其旧版 cliAddOptions 并列。无关的旧版字段不会泄漏到其他通道,且现代所选通道会拒绝其未声明的兼容标志。

通道所有标志的示例包括:

通道 标志
Google Chat --webhook-path, --webhook-url, --audience-type, --audience
通道 标志
iMessage --cli-path, --db-path, --service, --region
Matrix --homeserver, --user-id, --access-token, --password, --device-name, --initial-sync-limit
Nostr --private-key, --relay-urls
Signal --signal-number, --signal-transport, --cli-path, --http-url, --http-host, --http-port
Tlon --ship, --url, --code, --group-channels, --dm-allowlist, --auto-discover-channels
WhatsApp --auth-dir

如果通道插件需要在基于标志的添加命令期间安装,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?

如果你确认现在绑定,向导会询问每个已配置的通道账户应由哪个 agent 拥有,并写入账户级路由绑定。

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

当你向仍使用单账户顶层设置的通道添加非默认账户时,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 会警告其他凭据可能仍然有效;这并不表示提供商侧令牌已被吊销。
  • 登录和登出基于已编写的源进行配置更改,而不是运行时默认值。没有凭据可清除的登出不会仅因为运行时默认值被实例化就重写配置;有意的插件启用或安装更改仍可以保存。
  • 登录成功后,CLI 会请求可达的本地 Gateway 启动该账户。如果该启动被跳过,或另一个生命周期操作拥有该账户,它会报告原因和一个状态命令;保存的认证会保留。在远程模式下,它会在本地保存认证,并注明远程运行时未被重启。
  • 请在 gateway 主机上的终端中运行 channels login。Agent exec 会阻止此交互式登录流程;当可用时,应使用通道原生 agent 登录工具(例如 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 }。这些布尔值反映操作后账户的运行时快照:仅当 running 为 true 时,started 才为 true;当 running 不为 true 时,stopped 为 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(在已知处标注)。没有检查的通道会报告实时检查不可用。

将名称解析为 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>。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw