一文吃透OpenClaw日志系统：级别、配置、优先级，全程无废话

1. 本地跑 OpenClaw 后日志为什么总是不听话你刚在本地把 OpenClaw 跑起来openclaw gateway run一执行终端刷得飞快想看的调试信息一条没有等你把级别调成debug又被海量输出淹没真正报错的那一行反而找不到了。更迷惑的是明明配置文件里写了level: debug重启之后控制台还是只打印info级别的内容——这不是你配置写错了而是 OpenClaw 的日志系统有一套明确的优先级解析链路环境变量、CLI 参数、配置文件、默认值层层覆盖谁在最后生效取决于谁的位置更高。OpenClaw 的日志系统基于 tslog 构建核心特点是文件日志与控制台日志双通道独立配置级别从silent到trace共 7 档数值越低优先级越高。这套设计对本地部署的开发者来说非常实用你可以让文件日志安静地记录info级别用于事后排查同时让控制台在调试时临时提升到debug互不干扰。但它也带来一个副作用——如果你不清楚优先级规则就会出现「我明明改了配置却不生效」的情况。这篇内容面向已经完成 OpenClaw 本地部署、正在排查运行状态或调试问题的开发者。我会把 7 种日志级别的含义、4 种配置方式的写法、完整的优先级链路以及如何用 TaoToken 统一 Key/API 通道把 AI 工具链接入进来一次性讲清楚。全程给可复制的配置片段和验证动作你跟着敲一遍就能把日志系统吃透。2. 前置准备用 TaoToken 统一 Key 与 API 通道在深入日志配置之前先把 AI 工具链的接入通道理顺。本地部署 OpenClaw 之后你大概率会同时用到模型对话、代码补全、Agent 调用等多个 AI 能力如果每个工具单独配一套 Key 和 Base URL管理成本很高排查问题时也容易搞混是哪个通道出的错。TaoToken 的作用就是把这些能力收敛到一个统一的 Key 和 API 入口上。具体操作上你可以先到 TaoToken 控制台创建一个 API Key然后在 OpenClaw 的配置里把模型请求的 Base URL 指向https://taotoken.net/apiKey 填刚创建的那一串。这样无论是日志里记录的模型调用还是后续用 CC Switch 切换不同工具链都走同一个通道出问题时只需要检查一个地方。如果你更习惯用 Claude Code 这类编码工具TaoToken 也提供了对应的接入文档把 Anthropic 风格的请求转发到统一通道上。对于长期跑编码任务或 Agent 的场景Coding Plan 会比按量调用更划算适合把日志调试和日常开发放在同一套环境里。这里有个细节值得注意日志系统本身不依赖 TaoToken但当你用debug级别排查模型调用失败时日志里会打印出请求的 Base URL 和响应状态。如果通道配置混乱你会在日志里看到一堆指向不同地址的请求排查效率直线下降。所以先把通道统一再调日志级别顺序不能反。3. 可复制配置7 种级别与 4 种设置方式3.1 先认清 7 种日志级别OpenClaw 的级别定义在levels.ts里顺序是这样的export const ALLOWED_LOG_LEVELS [ silent, fatal, error, warn, info, debug, trace, ] as const;数值越低优先级越高。当你把级别设为info数值 3时只有fatal(0)、error(1)、warn(2)、info(3) 会被输出debug(4) 和trace(5) 被过滤掉。换句话说设置某个级别等于打开该级别及以上所有更严重的日志。silent是彻底关闭trace是最啰嗦的全量输出。3.2 方式一配置文件最推荐长期使用在 OpenClaw 配置文件的logging段里设置类型定义在types.base.ts{ logging: { level: debug, consoleLevel: warn, consoleStyle: json, file: /var/log/openclaw/openclaw.log, maxFileBytes: 104857600, redactSensitive: tools } }这里level控制文件日志consoleLevel单独控制控制台两者互不影响。consoleStyle可选pretty、compact、jsonTTY 环境默认pretty非 TTY 默认compact。maxFileBytes默认 500 MB超出后停止写入并在 stderr 发警告。3.3 方式二环境变量临时调试首选export OPENCLAW_LOG_LEVELdebug openclaw gateway run这个环境变量同时覆盖文件日志和控制台日志优先级高于配置文件。解析逻辑在env-log-level.ts如果你填了无效值它会输出一行警告然后忽略不会让程序崩溃export function resolveEnvLogLevelOverride(): LogLevel | undefined { const raw process.env.OPENCLAW_LOG_LEVEL; const trimmed typeof raw string ? raw.trim() : ; if (!trimmed) return undefined; const parsed tryParseLogLevel(trimmed); if (parsed) return parsed; process.stderr.write( [openclaw] Ignoring invalid OPENCLAW_LOG_LEVEL${trimmed} (allowed: ${ALLOWED_LOG_LEVELS.join(|)}).\n, ); return undefined; }3.4 方式三--verbose 标志只影响控制台openclaw gateway run --verbose--verbose只把控制台级别提升到debug文件日志级别不变。判断逻辑在console.ts的normalizeConsoleLevel()里isVerbose()为真时直接返回debug。3.5 方式四CLI --log-level 选项openclaw gateway run --log-level warn这个选项在 CLI 的 preAction 钩子里被写入环境变量所以它和直接设OPENCLAW_LOG_LEVEL效果等价属于同一优先级层。4. 优先级验证一条命令看清谁在生效4.1 完整优先级链路从高到低排列优先级来源影响范围1OPENCLAW_LOG_LEVEL环境变量文件 控制台2CLI--log-level选项等价于设环境变量3配置文件logging.level/consoleLevel可分别控制4--verbose标志仅控制台提升到 debug5默认值info测试环境silent最低优先级resolveSettings()是文件日志级别确定的核心函数决策流程可以简化为先检查能否用文件系统不能就silent再读环境变量然后走测试快速路径接着三级回退读配置运行时覆盖 → 配置缓存 → 完整加载最后level envLevel ?? fromConfig环境变量优先于配置文件。4.2 动手验证优先级第一步在配置文件里写level: warn启动openclaw gateway run你会看到控制台只输出warn及以上内容info被过滤。第二步不改配置直接加环境变量OPENCLAW_LOG_LEVELdebug openclaw gateway run控制台立刻变成debug级别说明环境变量压过了配置文件。第三步同时设环境变量和--verboseOPENCLAW_LOG_LEVELerror openclaw gateway run --verbose结果控制台是error级别不是debug。因为环境变量优先级高于--verbose--verbose只在没有更高优先级来源时才把控制台提到debug。4.3 测试环境的特殊行为测试环境下日志默认静默避免噪音。如果你在跑测试时想看日志需要显式打开OPENCLAW_TEST_FILE_LOG1 OPENCLAW_TEST_CONSOLE1 openclaw testOPENCLAW_TEST_FILE_LOG1启用测试文件日志OPENCLAW_TEST_CONSOLE1启用测试控制台日志不加这两个变量测试环境默认silent。5. 本篇常见错排查配置改了不生效九成是环境变量在作祟。先执行echo $OPENCLAW_LOG_LEVEL确认有没有残留值有就unset掉再重启。CLI 的--log-level也会写入环境变量检查启动命令里有没有带这个参数。控制台和文件日志级别不一致这是设计如此不是 bug。level管文件consoleLevel管控制台--verbose只动控制台。想让两者一致要么用OPENCLAW_LOG_LEVEL统一覆盖要么在配置里把两个字段设成同一个值。日志文件不生成先确认canUseNodeFs()返回是否为真容器环境里如果没挂载可写目录会直接走silent。再检查logging.file路径的父目录是否存在且可写默认路径是系统临时目录下的按日滚动文件openclaw-YYYY-MM-DD.log。日志文件写到 500 MB 后停了这是默认上限超出后停止写入并在 stderr 发警告。调大logging.maxFileBytes即可单位是字节比如 100 MB 写104857600。旧日志超过 24 小时会被pruneOldRollingLogs()自动清理。无效级别值导致程序异常不会。resolveEnvLogLevelOverride()遇到无效值只输出警告并返回undefined然后回退到配置文件或默认值。你会在 stderr 看到Ignoring invalid OPENCLAW_LOG_LEVEL...这行提示。模型调用失败但日志里看不到请求详情把级别临时提到debug或trace同时确认 TaoToken 的 Base URL 和 Key 配置正确。如果日志里请求地址五花八门说明通道没统一回到第 2 节把 Key 和 API 入口收敛到一处。6. 把日志调试接进你的 AI 工具链日志调通之后下一步是让它和你的日常开发流配合起来。我的做法是文件日志长期保持info用于事后回溯控制台在需要时用OPENCLAW_LOG_LEVELdebug临时打开排查完就关掉避免刷屏。模型调用的 Base URL 统一指向https://taotoken.net/apiKey 从 TaoToken 控制台创建这样日志里记录的请求地址始终一致出问题一眼就能定位。如果你经常切换不同的编码工具可以用 CC Switch 管理多套配置把 TaoToken 的 Key 作为公共通道填进去再配合settings.json骨架把日志相关的环境变量也写进去这样每次启动都自动带上正确的级别。需要长期跑 Agent 或编码任务的话Coding Plan 比按量调用更省心日志和通道都在同一套环境里排查链路短很多。最后留一个实用技巧把OPENCLAW_LOG_LEVEL写进你的 shell 启动脚本里注释掉需要时取消注释再source一下比每次手敲环境变量快得多。日志系统的价值不在于配置多复杂而在于你需要它的时候它能给出恰好够用的信息。