时区处理

概述

OpenClaw 标准化时间戳，使模型看到单一参考时间而非混合的 provider 本地时钟。时区在三个不同的表面出现，各有其用途。

核心要点

• 三个时区表面：消息信封（包裹入站 channel 消息）、工具载荷（readMessages 类工具返回原始 provider 时间 + 标准化 timestampMs/timestampUtc）、系统提示（仅包含时区，不含实时时钟值，保持缓存稳定性）
• 系统提示刻意省略实时时钟：避免破坏 prompt 缓存；Agent 需要当前时间时调用 session_status
• 默认值：消息信封和系统提示均默认使用宿主时区；工具载荷的 UTC 字段始终存在
• 配置分离：envelopeTimezone 控制信封时区；userTimezone 控制系统提示时区；两者独立配置

配置/使用

设置用户时区：

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago"
    }
  }
}

信封时区配置：

{
  agents: {
    defaults: {
      envelopeTimezone: "utc"  // 或 "Europe/Vienna" 等 IANA 时区
    }
  }
}

时间格式：

{
  agents: {
    defaults: {
      timeFormat: "24"  // "auto" | "12" | "24"
    }
  }
}

使用场景：

• UTC 信封（envelopeTimezone: "utc"）：跨不同地区宿主保持稳定时间戳，或与诊断日志对齐
• 固定 IANA 时区：Gateway 宿主在一个时区，用户在另一个时区时
• 关闭信封时间戳（envelopeTimestamp: "off"）：减少 token 消耗，当时间戳上下文对对话无用时

相关页面

• system-prompt — 系统提示词结构（包含时区块）
• context — 上下文组成与构建
• session — 会话路由与生命周期
• messages — 消息处理流水线