通道投递与工具
通道已连接,消息未流转¶
如果通道状态为已连接但消息流中断,请重点关注策略、权限以及通道特定的投递规则。
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels
查找:
- DM 策略(
pairing、allowlist、open、disabled)。 - 群组允许列表和提及要求。
- 缺失的通道 API 权限/作用域。
常见特征:
mention required→ 消息被群组提及策略忽略。pairing/ 待审批痕迹 → 发送者未获批准。missing_scope、not_in_channel、Forbidden、401/403→ 通道认证/权限问题。
相关:
Cron 与 heartbeat 投递¶
如果 cron 或 heartbeat 未运行或未投递,请先验证调度器状态,再检查投递目标。
openclaw automations status
openclaw automations list
openclaw automations runs <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
查找:
- Cron 已启用且存在下次唤醒时间。
- 作业运行历史状态(
ok、skipped、error)。 - Heartbeat 跳过原因(
quiet-hours、requests-in-flight、cron-in-progress、alerts-disabled、empty-heartbeat-file)。
常见特征
cron: scheduler disabled; jobs will not run automatically→ cron 已禁用。cron: timer tick failed→ 调度器 tick 失败;检查文件/日志/运行时错误。heartbeat skipped且reason=quiet-hours→ 处于活动时段窗口之外。heartbeat skipped且reason=empty-heartbeat-file→ heartbeat 监控草稿仅包含空白、注释、标题、围栏或空清单脚手架,因此 OpenClaw 跳过模型调用。heartbeat skipped且reason=no-route→ 默认owner目标在commands.ownerAllowFrom或通道allowFrom中没有具体 owner,owner 无法解析为 DM,或未配置通道。显式last也需要会话对话路由。heartbeat: unknown accountId→ heartbeat 投递目标的账户 ID 无效。session event wake failed; no wake retry scheduled→ 一次唤醒以失败结束。错误日志记录了其来源、意图、agent/session 目标、唤醒原因和错误。在请求另一次唤醒之前,检查该会话并修复报告的原因;唤醒调度器不会重放失败的回合,这些回合可能已经执行了工作。已被持久化投递队列持有的出站消息仍遵循其独立的恢复策略。heartbeat skipped且reason=dm-blocked→ heartbeat 目标解析为 DM 风格目的地,而agents.defaults.heartbeat.directPolicy(或按 agent 覆盖)设置为block。
相关:
节点已配对,工具失败¶
如果节点已配对但工具失败,请分别排查前台、权限和审批状态。
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
查找:
- 节点在线且具备预期能力。
- 摄像头/麦克风/位置/屏幕的操作系统权限授予。
- Exec 审批和允许列表状态。
常见特征:
NODE_BACKGROUND_UNAVAILABLE→ 节点应用必须处于前台。*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ 缺少操作系统权限。SYSTEM_RUN_DENIED: approval required→ exec 审批待处理。SYSTEM_RUN_DENIED: allowlist miss→ 命令被允许列表阻止。
相关:
浏览器工具失败¶
当浏览器工具操作失败,但网关本身健康时使用。
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
查找:
- 是否设置了
plugins.allow并且包含browser。 - 有效的浏览器可执行文件路径。
- CDP 配置文件可达性。
existing-session/user配置文件的本地 Chrome 可用性。
插件 / 可执行文件特征
unknown command "browser"或unknown command 'browser'→ 捆绑的浏览器插件被plugins.allow排除。- 在
browser.enabled=true时浏览器工具缺失/不可用 →plugins.allow排除了browser,因此插件从未加载。 Failed to start Chrome CDP on port→ 浏览器进程启动失败。browser.executablePath not found→ 配置的路径无效。browser.cdpUrl must be http(s) or ws(s)→ 配置的 CDP URL 使用了不支持的方案,例如file:或ftp:。browser.cdpUrl has invalid port→ 配置的 CDP URL 端口无效或超出范围。Playwright is not available in this gateway build; '<feature>' is unsupported.→ 当前网关安装缺少核心浏览器运行时依赖;重新安装或更新 OpenClaw,然后重启网关。ARIA 快照和基本页面截图仍可工作,但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。
Chrome MCP / existing-session 特征
Could not find DevToolsActivePort for chrome→ Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。打开浏览器检查页面,启用远程调试,保持浏览器打开,批准首次附加提示,然后重试。如果不需要已登录状态,请优先使用托管的openclaw配置文件。No browser tabs found for profile="user"→ Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。Remote CDP for profile "<name>" is not reachable→ 配置的远程 CDP 端点无法从网关主机访问。Browser attachOnly is enabled ... not reachable或Browser attachOnly is enabled and CDP websocket ... is not reachable→ 仅附加配置文件没有可达目标,或 HTTP 端点有响应但 CDP WebSocket 仍无法打开。
元素 / 截图 / 上传签名
fullPage is not supported for element screenshots→ 截图请求将--full-page与--ref或--element混用。element screenshots are not supported for existing-session profiles; use ref from snapshot.→ Chrome MCP /existing-session截图调用必须使用页面捕获或快照--ref,而不是 CSS--element。existing-session file uploads do not support element selectors; use ref/inputRef.→ Chrome MCP 上传钩子需要使用快照引用,而不是 CSS 选择器。existing-session file uploads currently support one file at a time.→ 在 Chrome MCP 配置文件中,每次调用只发送一个上传。existing-session dialog handling does not support timeoutMs.→ Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。existing-session type does not support timeoutMs overrides.→ 对于profile="user"/ Chrome MCP existing-session 配置文件中的act:type,请省略timeoutMs;如需自定义超时,请使用托管/CDP 浏览器配置文件。response body is not supported for existing-session profiles yet.→responsebody目前仍需要托管浏览器或原始 CDP 配置文件。- 在 attach-only 或远程 CDP 配置文件中,过期的视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行
openclaw browser stop --browser-profile <name>以关闭当前活动控制会话,并释放 Playwright/CDP 模拟状态,而无需重启整个网关。
Related:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw