OpenClaw 通过三个独立层面处理时区：消息信封显示用户可读时间（默认主机本地时区），工具载荷保留原始提供商时间戳并附加 UTC 标准化字段，系统提示词仅含时区名（无实时时钟）以保证缓存稳定。配置入口在 agents.defaults 下的 envelopeTimezone、userTimezone 和 timeFormat。当网关主机与用户不在同一时区、或需要跨区域统一日志时，建议显式设置 IANA 时区或锁定为 UTC。

OpenClaw 时区配置与时间戳处理

OpenClaw 对时间戳做统一标准化，让模型始终看到 同一参考时间，避免各提供商本地时钟混乱。时区影响体现在三个独立层面，每个层面有不同用途和配置方式。

三个时区层面

层面	显示内容	默认值	配置入口
消息信封	入站渠道消息包装：[Signal +1555 2026-01-18 00:19 PST] hello	主机本地时间	agents.defaults.envelopeTimezone
工具载荷	渠道 readMessages 类工具返回原始提供商时间 + 标准化字段 timestampMs / timestampUtc	UTC 字段始终存在	不可配置 — 保留提供商原始时间戳
系统提示词	一个小型 Current Date & Time 区块，仅含时区名（无实时时钟值，保持缓存稳定）	userTimezone 未设置时使用主机时区	agents.defaults.userTimezone

系统提示词特意省略了实时时钟，以保证跨轮对话时提示缓存稳定。当智能体需要当前时间时，应调用 session_status 工具获取。

配置用户时区

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

如果 userTimezone 未设置，OpenClaw 在运行时自动解析主机时区（不写入配置）。agents.defaults.timeFormat（auto | 12 | 24）控制信封和下游层面的 12/24 小时制渲染，不影响系统提示词中的时区区块。

覆盖时机

• 使用 UTC 信封（envelopeTimezone: "utc"）：当网关主机分布在不同区域，希望获得统一时间戳对齐日志和诊断输出时。
• 固定 IANA 时区（如 "Europe/Vienna"）：当网关在一个时区，用户在另一个时区，希望信封始终按用户时区读取，不受主机迁移影响时。
• 关闭时间戳（envelopeTimestamp: "off"）：消息上下文对时间不敏感时，减少信封 token 占用。

完整行为参考、各提供商示例及经过时间格式化，详见 Date & Time。

相关文档

• Date & Time — 完整的信封/工具/提示词行为及示例
• Heartbeat — 活跃时段使用时区调度
• Cron Jobs — cron 表达式使用时区调度

常见问题

消息信封里的时间是哪个时区？

默认是运行 OpenClaw 网关的主机本地时区。你可以通过 agents.defaults.envelopeTimezone 改为 "utc"、"user" 或任意 IANA 时区（如 "Asia/Shanghai"）。

系统提示词里为什么不显示实时时钟？

为了保持提示缓存跨对话轮稳定。OpenClaw 故意不把实时时钟写入系统提示词，智能体需要当前时间时应调用 session_status 工具获取。

设置 userTimezone 后会影响哪些地方？

影响系统提示词中 Current Date & Time 区块的时区名显示，以及 envelopeTimezone 设为 "user" 时信封的时间渲染。不影响工具载荷的原始时间戳和标准化 UTC 字段。