openclaw logs 一次能取多少：–limit 数的是记录、250 KB 窗口只覆盖日志的 1.28%、–max-bytes 还有个 1 MB 天花板
更新时间：2026-11-03 14:18（Asia/Shanghai） 测量环境：macOS 26.6.2（arm64），OpenClaw 2026.10.10（7dc3350），Gateway 正在运行（本机 loopback:18789）
openclaw logs 只有三个数字参数：--limit、--max-bytes、--interval。文档把它们的默认值写得很清楚，但真正决定”这一次能看到多少行”的，是这两个上限谁先到，以及一个文档没有写的服务端上限。本文用 2026-11-03 14:00–14:15 在同一台机器上的十余次调用结果，把取数边界逐条标出来。所有数字都是实测，没有估算。
先说结论
- 默认一次返回 200 条记录、216,970 字节 stdout。
--limit 200先到，--max-bytes 250000没到。 --limit数的是记录，不是物理行。同一次默认调用在文本模式下输出 296 行，因为一条记录里的 message 可能自带换行。- 两个上限取小：
--limit 400只回来 289 条，因为 250,000 字节的窗口先装满了；把--max-bytes提到 1,000,000 后同样参数能回满 400 条。 --max-bytes有服务端天花板：1,000,000。传 1,000,001 直接退出码 1，错误是invalid logs.tail params: at /maxBytes: must be <= 1000000，文档只写了”必须是正整数”。- 默认窗口 250 KB，对本机活动日志文件（19,511,567 字节）只覆盖 1.28%；就算顶格 1 MB，也只有 5.13%。想看更早的内容，只能反复取窗口或直接读文件。
- 参数写错时（
--limit 0、--limit abc、--max-bytes 0、--port 0），退出码是 1，但 stderr 只有[openclaw] The CLI command failed.和 doctor 建议，没有指出是哪个选项错了——与文档承诺不一致。唯一给具体提示的是--utc与--local-time同时出现。
一、两个上限，取小的那个
文档对两个参数的描述分别是 “max log lines to return (default 200)” 和 “max bytes to read from the log file (default 250000)”。实测把这两个值同时压上去时，结果只由先到的那一个决定：
openclaw logs --json 参数 |
退出码 | log 记录数 | stdout 字节 | 谁先生效 |
|---|---|---|---|---|
| （默认） | 0 | 200 | 216,970 | --limit 200 |
--limit 100 |
0 | 100 | 127,592 | --limit |
--limit 400 |
0 | 289 | 352,199 | --max-bytes 250000 |
--limit 400 --max-bytes 1000000 |
0 | 400 | 452,258 | --limit |
--max-bytes 100000 |
0 | 86 | 138,793 | --max-bytes |
--max-bytes 10000 |
0 | 6 | 7,111 | --max-bytes |
--max-bytes 1000001 |
1 | 0 | 0 | 网关拒绝 |
--limit 0 |
1 | 0 | 0 | 参数校验失败 |
注意第三行和第四行的对比：同样是 --limit 400，只改 --max-bytes，返回的条数从 289 跳到 400。这说明 --limit 不是”必然给你这么多条”，而是”最多给这么多条”。
还有一个更容易被忽略的现象：同一组参数，隔几分钟结果会变。同一轮测量里先跑 --limit 300 拿到 300 条（340,623 字节），隔了几分钟再跑同样参数只有 289 条（352,199 字节）。原因是这段尾部的记录变长了，250 KB 窗口里能塞下的条数自然变少。任何”先按条数估算字节”的脚本都会在这种漂移上出错。
二、--limit 数的是记录，不是行
默认调用在文本模式下输出 296 行、36,415 字节，但 JSON 模式下明确是 200 条 type: "log" 记录。差的 96 行来自 message 字段里的换行——一条记录可以横跨几十行终端。
这对排障有两个直接影响：
- 用
wc -l数文本输出，得到的不是条数。要数字节或记录数，用--json再按"type":"log"计数。 - 文本模式第一行是
Log file: /Users/kevin/Library/Logs/openclaw/gateway.jsonl，最后一行是Log tail truncated (increase --limit or --max-bytes).。这两行都不是日志记录，混在同一条 stdout 流里。
关于最后那行提示：它每次都会出现。--limit 100、--limit 400、--max-bytes 10000 的调用全都带这一行。所以它不是”你参数给太小”的信号，只是”窗口之外还有更早的日志”。在 JSON 模式下它是 {"type":"notice","message":"Log tail truncated (increase --limit or --max-bytes)."}，和其他记录一起排在 stdout 里；脚本如果不按 type 过滤，会把它当成第 201 条记录。
三、1 MB 的服务端天花板
--max-bytes 的校验发生在 Gateway 的 logs.tail 方法里，不是 CLI 本地。传 1,000,001 的结果：
invalid logs.tail params: at /maxBytes: must be <= 1000000
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /Users/kevin/.openclaw/openclaw.json
Bind: loopback
Hint: run `openclaw doctor`.退出码 1，stdout 为空。文本模式和 JSON 模式的差别只在最后一条：JSON 模式把同样的原因和连接详情包进 {"type":"error",...}，写在 stderr。
这对”一次多取一点”的想法是硬限制。按本机平均每行 967.4 字节算，1 MB 大约 1,034 行；对 20,169 行的活动文件，一次调用最多看到 5.13%。要覆盖整天的日志，靠 --max-bytes 反复加码是走不通的——顶格之后只能自己按文件读。
四、日志文件在哪、有多大、转几次
本机的日志并不在文档写的 /tmp/openclaw/openclaw-YYYY-MM-DD.log。配置里 logging.file 被显式指到了 ~/Library/Logs/openclaw/gateway.jsonl，logging.maxFileBytes 是 20,000,000（文档默认 100 MB）。openclaw logs 第一行打印的路径就是这个配置值，所以看输出就知道在读哪个文件，不必猜。
2026-11-03 14:02:58 的文件清单：
| 文件 | 字节 | 行数 | 最后写入 |
|---|---|---|---|
gateway.jsonl（活动） |
19,511,567 | 20,169 | 2026-11-03 14:02:52 |
gateway.1.jsonl |
19,999,703 | 20,079 | 2026-11-01 18:22:04 |
gateway.2.jsonl |
19,999,828 | 21,394 | 2026-10-30 17:21:46 |
gateway.log |
8,040,693 | 56,945 | 2026-11-03 14:02:52 |
node.log |
18,979 | 163 | 2026-10-30 17:43:40 |
ollama-memory-error.log |
21,446,078 | 335,053 | 2026-10-23 18:24:09 |
| 目录合计 | 89,016,848 | — | — |
从这张表能读出三件事：
- 轮转确实按 20 MB 走。 两个归档都是 19,999,7xx 字节，正好卡在阈值下，活动文件涨到 19.5 MB。配置的
maxFileBytes生效，不是文档默认的 100 MB。 - 只看到 2 个归档，文档说最多 5 个。 目录里没有
.3、.4、.5。较早的归档是被删了还是从未生成，本机证据不足以判断（UNKNOWN）。 gateway.log是另一份 8 MB 的文本日志，56,945 行，与gateway.jsonl同步写入。它不在openclaw logs的读取路径上（命令读的是logging.file指的 jsonl），但磁盘占用要算进总量。
另外，/tmp/openclaw/ 里还躺着一份 openclaw-2026-10-30.log（4,570 字节，10 月 30 日 10:16 写入）。文档说”按天命名的日志 24 小时后清理”，这份已经放了 4 天。为什么没清，可能与”改用自定义 logging.file 后不再生成新的按天文件、清理只在生成时触发”有关，但这一点我没有验证，标为 UNKNOWN。
五、参数写错时的提示，和文档对不上
文档原话是：--limit、--max-bytes、--interval “require positive integers. Invalid values exit with status 1 and name the option and accepted values on stderr, without requiring debug mode.”
实测四种非法输入，stderr 都只有两行通用文案：
| 输入 | 退出码 | stderr |
|---|---|---|
--limit 0 |
1 | [openclaw] The CLI command failed. + For help, run \openclaw doctor\. |
--limit abc |
1 | 同上（连 “abc” 都没提） |
--max-bytes 0 |
1 | 同上 |
--port 0 |
1 | 同上 |
--utc --local-time |
1 | Pass only one of --local-time or --utc. |
只有互斥参数那一组给出了具体原因。这意味着在 CI 里拼命令时，参数拼错的表现和”网关连不上”是同一个退出码、同一种文案，只能靠退出码拦，没法从 stderr 判断该改哪个参数。要定位只能临时打开 debug 日志重跑。
六、把这些事实用进取日志的脚本
基于上面的实测，本机排障时我按这套顺序取日志：
- 先确认在读哪个文件。 跑一次文本模式，看第一行
Log file:；路径和预期不符时，先查logging.file，别去/tmp/openclaw/找。 - 要结构化数据就用
--json，并按type过滤。 只保留type == "log"的记录，meta用来拿文件路径和 cursor，notice单独处理，error走 stderr 判断。 - 别指望一次取全。 默认 200 条 / 250 KB；要更早的内容，把
--max-bytes顶到 1,000,000（约 1,000 行），再往前就得直接读文件：gateway.1.jsonl、gateway.2.jsonl里是完整的历史。 - 按字节估算时要留余量。 记录长度在分钟级就会漂移（同一参数 300 条与 289 条），不要把”条数 × 平均行长”当成硬预算。
- 监控目录体积，不只监控单文件。 本机 89 MB 里，活动文件只占 22%，两份归档占 45%，
gateway.log和ollama-memory-error.log又占 33%。只看logging.file会漏掉大头。
事实来源与未验证项
- 文档：
openclaw logsCLI 参考、Logging 概览、Gateway logging；抓取时间 2026-11-03 14:00–14:05，均 HTTP 200。 - 本机命令：
openclaw logs --help、openclaw logs --json（默认与 8 组参数）、openclaw logs --plain、openclaw logs --max-bytes 1000001 --plain，执行时间 2026-11-03 14:00–14:15。 - 本机配置：
openclaw config get logging→file=~/Library/Logs/openclaw/gateway.jsonl，maxFileBytes= 20,000,000。 - 文件统计：
wc -c/wc -l/stat，快照 2026-11-03 14:02:58。 - UNKNOWN：为什么只有 2 个编号归档（文档说最多 5 个）；
/tmp/openclaw/openclaw-2026-10-30.log为何超过 24 小时未被清理；--limit是否存在服务端上限（本次最高测到 5,000，被字节窗口先截断，未触及条数上限）。 - 本文只做只读观测，没有修改日志配置、没有删除或轮转任何文件，也没有测试
--follow的重连与 journal 回退路径。
