openClaw 的日志系统基于 tslog 构建，提供了灵活的多级别日志能力，支持文件日志和控制台日志双通道独立配置。日志级别可通过配置文件、环境变量、CLI 选项等多种方式控制，并遵循明确的优先级解析链路。

一、7 种日志级别

日志级别定义在 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）会被过滤掉。

二、默认日志级别

默认级别的确定逻辑位于 logger.ts 的 resolveSettings() 函数中：

const defaultLevel =
  process.env.VITEST === "true" && process.env.OPENCLAW_TEST_FILE_LOG !== "1"
    ? "silent"
    : "info";

文件日志默认级别

生产环境 info 记录关键运行时事件 测试环境（VITEST=true） silent 避免测试输出噪音 测试环境 + OPENCLAW_TEST_FILE_LOG=1 info 显式启用测试文件日志

控制台日志默认级别

控制台日志的默认级别逻辑在 console.ts 的 normalizeConsoleLevel() 中：

环境 默认级别 说明 生产环境 info 与文件日志一致 测试环境 silent 避免测试输出噪音 --verbose 模式 debug 自动提升到调试级别

其他默认值

配置项 默认值 说明 日志文件路径 /openclaw-YYYY-MM-DD.log 按日滚动 日志文件大小上限 500 MB 超出后停止写入并发出警告 控制台输出样式 TTY: pretty / 非 TTY: compact 自动适配终端类型

三、resolveSettings() 核心解析流程

resolveSettings() 是文件日志级别确定的核心函数，其决策流程如下：

resolveSettings()
│
├─ canUseNodeFs() = false ──────────────────► level: "silent"
│                                              (无法使用文件系统)
│
├─ envLevel = resolveEnvLogLevelOverride()
│  └─ 读取 OPENCLAW_LOG_LEVEL 环境变量
│
├─ canUseSilentVitestFileLogFastPath() ─────► level: "silent"
│  (VITEST=true 且无 envLevel 且无 override)   (测试快速路径)
│
├─ 读取配置（三级回退）：
│  ├─ loggingState.overrideSettings            (运行时覆盖)
│  ├─ readLoggingConfig()                      (已加载的配置缓存)
│  └─ loadConfig().logging                     (完整加载配置文件)
│
├─ defaultLevel = VITEST && !TEST_FILE_LOG ? "silent" : "info"
│
├─ fromConfig = normalizeLogLevel(cfg?.level, defaultLevel)
│
└─ level = envLevel ?? fromConfig
   │
   └─ 最终级别：环境变量 > 配置文件 > 默认值

关键代码段（ logger.ts:96-137 ）：

function resolveSettings(): ResolvedSettings {
  if (!canUseNodeFs()) {
    return { level: "silent", file: DEFAULT_LOG_FILE, maxFileBytes: 
    DEFAULT_MAX_LOG_FILE_BYTES };
  }

  const envLevel = resolveEnvLogLevelOverride();

  if (canUseSilentVitestFileLogFastPath(envLevel)) {
    return { level: "silent", file: defaultRollingPathForToday(), maxFileBytes: 
    DEFAULT_MAX_LOG_FILE_BYTES };
  }

  let cfg = (loggingState.overrideSettings as LoggerSettings | null) ?? 
  readLoggingConfig();
  if (!cfg && !shouldSkipMutatingLoggingConfigRead()) {
    try {
      const loaded = requireConfig?.("../config/config.js");
      cfg = loaded?.loadConfig?.().logging;
    } catch { cfg = undefined; }
  }

  const defaultLevel =
    process.env.VITEST === "true" && process.env.OPENCLAW_TEST_FILE_LOG !== "1" ? 
    "silent" : "info";
  const fromConfig = normalizeLogLevel(cfg?.level, defaultLevel);
  const level = envLevel ?? fromConfig;
  const file = cfg?.file ?? defaultRollingPathForToday();
  const maxFileBytes = resolveMaxLogFileBytes(cfg?.maxFileBytes);
  return { level, file, maxFileBytes };
}

四、配置日志级别的 4 种方式

方式一：配置文件

在 OpenClaw 配置文件中通过 logging 配置段设置。类型定义位于 types.base.ts:168-179 ：

export type LoggingConfig = {
  level?: "silent" | "fatal" | "error" | "warn" | "info" | "debug" | "trace";
  file?: string;
  maxFileBytes?: number;
  consoleLevel?: "silent" | "fatal" | "error" | "warn" | "info" | "debug" | 
  "trace";
  consoleStyle?: "pretty" | "compact" | "json";
  redactSensitive?: "off" | "tools";
  redactPatterns?: string[];
};

配置示例：

{
  "logging": {
    "level": "debug",
    "consoleLevel": "warn",
    "consoleStyle": "json",
    "file": "/var/log/openclaw/openclaw.log",
    "maxFileBytes": 104857600,
    "redactSensitive": "tools"
  }
}

字段 说明 level 文件日志级别 consoleLevel 控制台日志级别（可独立于文件日志设置） consoleStyle 控制台输出样式： pretty （彩色格式化）、 compact （紧凑）、 json （JSON 结构化） file 日志文件路径 maxFileBytes 日志文件大小上限（字节） redactSensitive 敏感信息脱敏策略： off （关闭）、 tools （工具调用中脱敏） redactPatterns 自定义脱敏正则模式列表

方式二：环境变量 OPENCLAW_LOG_LEVEL

export OPENCLAW_LOG_LEVEL=debug

此环境变量 同时覆盖文件日志和控制台日志 的级别，优先级高于配置文件。解析逻辑在 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;
}

如果设置了无效值，会输出警告并忽略，不会导致程序崩溃。

方式三：–verbose 标志

openclaw gateway run --verbose

–verbose 仅影响控制台日志，自动将控制台级别提升到 debug 。它不影响文件日志级别。判断逻辑在 console.ts ：

function normalizeConsoleLevel(level?: string): LogLevel {
  if (isVerbose()) {
    return "debug";
  }
  if (!level && process.env.VITEST === "true" && process.env.OPENCLAW_TEST_CONSOLE 
  !== "1") {
    return "silent";
  }
  return normalizeLogLevel(level, "info");
}

五、日志级别优先级（从高到低）

┌─────────────────────────────────────────────────────────────┐
│  1. OPENCLAW_LOG_LEVEL 环境变量          ← 最高优先级       │
│     ↓ (未设置时)                                             │
│  2. CLI --log-level 选项                  ← 等价于设置环境变量│
│     ↓ (未设置时)                                             │
│  3. 配置文件 logging.level / consoleLevel ← 可分别控制       │
│     ↓ (未设置时)                                             │
│  4. --verbose 标志                        ← 仅控制台提升到debug│
│     ↓ (未启用时)                                             │
│  5. 默认值 info（测试环境 silent）        ← 最低优先级       │
└─────────────────────────────────────────────────────────────┘

六、测试专用环境变量

测试环境下日志默认静默，可通过以下环境变量显式启用：

环境变量 作用
OPENCLAW_TEST_FILE_LOG=1 测试环境下启用文件日志（否则默认 silent ）
OPENCLAW_TEST_CONSOLE=1 测试环境下启用控制台日志（否则默认 silent ）
OPENCLAW_LOG_LEVEL=debug 全局覆盖（同生产环境用法）

七、日志文件管理

滚动策略

  • 日志文件按日滚动，命名格式： openclaw-YYYY-MM-DD.log
  • 默认存放目录：系统临时目录下的 OpenClaw 专用路径
  • 自动清理超过 24 小时的旧日志文件（ logger.ts:354-378 的 pruneOldRollingLogs() ）

大小限制

  • 默认上限：500 MB
  • 超出上限后停止写入，并在 stderr 输出警告
  • 可通过 logging.maxFileBytes 配置项自定义

八、关键源码文件索引

文件 作用
src/logging/levels.ts 日志级别枚举、解析、数值映射
src/logging/env-log-level.ts OPENCLAW_LOG_LEVEL 环境变量解析
src/logging/logger.ts 文件日志器创建、设置解析、默认值
src/logging/console.ts 控制台日志设置、样式、级别解析
src/logging/state.ts 日志全局状态（缓存、覆盖等）
src/logging/config.ts 从配置文件读取 logging 配置段
src/config/types.base.ts LoggingConfig 类型定义
src/config/zod-schema.ts Zod 验证 Schema src/cli/log-level-option.ts CLI --log-level 选项解析 src/cli/program/preaction.ts CLI preAction 钩子，将 --log-level 写入环境变量

总结

OpenClaw 的日志系统设计遵循以下原则：

  1. 双通道独立控制 ：文件日志和控制台日志可分别设置级别，满足不同场景需求
  2. 多层优先级覆盖 ：从环境变量到配置文件再到默认值，提供了灵活的运行时控制能力
  3. 测试友好 ：测试环境默认静默，避免噪音，同时提供专用环境变量按需启用
  4. 安全脱敏 ：支持敏感信息脱敏策略，防止日志泄露敏感数据
  5. 自动管理 ：日志文件按日滚动、自动清理、大小限制，无需人工维护
# java # javascript # 自然语言处理 # 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

当长期记忆向量库遭遇投毒攻击：如何用相似度阈值与安全分类器构建防御圈

avatar 龙虾开发者社区
cover

Agent 网关密钥管理：如何用 ClawBridge 实现多模型路由与动态轮换

avatar 龙虾开发者社区
cover

ClawOS immutable根文件系统实战：Agent乱写防护与OOM杀进程策略

avatar 龙虾开发者社区