跳转至

openclaw logs

通过 RPC 实时跟踪 Gateway 文件日志。支持远程模式。

选项

  • --limit <n>:返回的最大日志行数(默认 200)
  • --max-bytes <n>:从日志文件读取的最大字节数(默认 250000)
  • --follow:跟踪日志流
  • --interval <ms>:跟踪时的轮询间隔(默认 1000)
  • --json:输出按行分隔的 JSON 事件
  • --plain:输出不带样式格式的纯文本
  • --no-color:禁用 ANSI 颜色
  • --local-time:以本地时区渲染时间戳(默认)
  • --utc:以 UTC 渲染时间戳

大于 2,147,000,000 ms 的轮询间隔会被限制为该值,以避免定时器溢出。

共享 Gateway RPC 选项

  • --url <url>:Gateway WebSocket URL
  • --port <port>:选择本地 Gateway 端口,覆盖已配置的远程 URL 和 OPENCLAW_GATEWAY_URL;不能与 --url 组合使用
  • --token <token>:Gateway token
  • --timeout <ms>:超时时间(毫秒,默认 30000)
  • --expect-final:当 Gateway 调用由 agent 支持时,等待最终响应

传入 --url 会跳过自动应用的配置凭据;如果目标 Gateway 需要身份验证,请显式包含 --token。

--port 需要 1 到 65535 之间的整数;空值或仅包含空格的值无效。省略该选项以使用已配置的目标或环境变量目标。

示例

openclaw logs
openclaw logs --follow
openclaw --dev logs --follow
openclaw --profile work logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --utc
openclaw logs --follow --local-time
openclaw logs --port 19083 --json
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

所选的根 profile 与 Gateway 的滚动文件匹配:默认 profile 使用 openclaw-YYYY-MM-DD.log,而命名 profile 使用 openclaw-<profile>-YYYY-MM-DD.log(例如,openclaw-dev-YYYY-MM-DD.log)。

回退与恢复行为

  • 如果无法读取或解析本地配置,openclaw logs 会读取本地文件日志,并给出 openclaw doctor --fix 指引的警告。该恢复方式同样适用于 --follow;显式 URL 目标仍保留其身份验证要求。
  • 如果隐式本地回环 Gateway 请求配对、在连接期间关闭,或在 logs.tail 响应前超时,openclaw logs 会自动回退到已配置的 Gateway 文件日志。显式 --url 目标从不使用此回退。
  • 在隐式本地 Gateway RPC 失败后,--follow 不会回退到该已配置文件——过时的并排文件可能会误导实时跟踪。在 Linux 上,如果可用,它会改为按 PID 使用活动的 user-systemd Gateway journal(打印所选来源);否则它会持续重试实时 Gateway。
  • 在 --follow 期间,瞬时断开连接(WebSocket 关闭、超时、连接中断)会触发带指数退避的自动重连:最多重试 8 次,尝试之间的间隔上限为 30 秒。每次重试都会向 stderr 打印警告,一旦某次轮询成功,就会打印一次 [logs] gateway reconnected 通知。在 --json 模式下,两者都会作为 {"type":"notice"} 记录输出到 stderr。身份验证和无效目标错误仍会立即退出。
  • 在 --follow --json 模式下,日志来源转换会作为 {"type":"meta"} 记录输出。按 sourceKind 跟踪游标:流可以从 Gateway 文件输出(sourceKind: "file")切换到本地 journal 回退(sourceKind: "journal"、localFallback: true,并带有 service.pid/service.unit),恢复后再切回 Gateway 文件输出。不要假设整个会话只有一个稳定的来源或游标,并在恢复重放 Gateway 文件游标时容忍重叠的行。

在 --json 模式下,无效的 --port、--limit、--interval 或 --max-bytes 值以及冲突的 --url/--port 选项会在 stdout 上产生标准 CLI 失败封装:{"ok":false,"error":{"type":"cli_error","message":"..."}}。终端日志获取失败则会在 stderr 上输出 {"type":"error",...}。两者均以状态 1 退出。

在文本模式下,终端日志获取失败会在 stderr 上打印已脱敏的错误原因、所选 Gateway 连接详情以及 doctor 提示。收到的 RPC 拒绝会作为错误显示,而不是报告为 Gateway 可达性失败。

在 JSON 模式下,终端日志获取错误对 message 和 error 使用相同的已脱敏失败原因,包括 RPC 拒绝、超时、断开连接和无效响应负载。该记录在 stderr 上保留连接 details 和 doctor hint;命令仍以状态 1 退出。

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