Concepts 导读

时区统一:信封时间戳、工具时间戳、系统提示时间

OpenClaw 把消息时间戳统一为“信封本地时间”,默认用主机时区,可全局改为 UTC、用户时区或固定 IANA 时区。工具调用返回原始提供者时间戳,同时附加 UTC 毫秒和 ISO 字符串。别忘了设 `userTimezone`,否则模型不知道用户在哪。

先讲这一页到底在解决什么

时区统一:信封时间戳、工具时间戳、系统提示时间

OpenClaw 把消息时间戳统一为“信封本地时间”,默认用主机时区,可全局改为 UTC、用户时区或固定 IANA 时区。工具调用返回原始提供者时间戳,同时附加 UTC 毫秒和 ISO 字符串。别忘了设 `userTimezone`,否则模型不知道用户在哪。

原文共 5 节,先看 Start Here 路径:/concepts/timezone 查看官方原文

第一站

📮 消息包头上的时间,默认跟着主机本地钟走

也就是你看到类似 [Provider ... 2026-01-05 16:26 PST] 那类前缀时,它先看的是宿主机时间。

envelopeTimezone: "local"

默认做法,像“用这台机器墙上的钟”。

"utc"

像全办公室统一挂一面世界标准钟,所有人都看 UTC。

"user"

像说“别看机器钟了,按用户自己的城市时区来写”。

IANA 时区

你也能直接指定 Europe/Vienna 这种固定城市时区,相当于锁死看某一座城的钟。

第二站

⏱️ 这几个开关,控制的是“包头上写不写绝对时间、写不写过去了几分钟”

有时候你想让模型更看重相对时间,有时候你想让它只看干净正文。

🗓️

envelopeTimestamp

关掉后,消息前缀里就不再写明确的年月日时分。

envelopeElapsed

关掉后,像 +2m 这种“刚刚过去两分钟”的小尾巴就会消失。

🧾

Raw tool timestamps

工具返回里仍会保留 provider 原始时间,但同时再附上标准化字段,方便统一比较。

🌍

timestampUtc

像给每条时间再贴一张世界统一标签,不用猜时区偏移。

第三站

👤 userTimezone 是专门告诉模型“用户平时活在哪个时间带”

这不是装饰字段。日程、提醒、今天明天、上午下午,很多理解都靠它。

agents.defaults.userTimezone

像把“用户常驻城市”贴给模型看。没写时会退回主机时区。

timeFormat: "12" / "24"

这像决定墙上钟表是上午下午制,还是 24 小时制。

系统提示词

官方会把当前日期时间和时区写进系统提示词里,不让模型瞎猜“现在几点”。

🎈 最后记一句

这页的主线只有一句:先统一钟表,再让模型聊天,不然时间理解很容易歪。