設定 OpenClaw 時區：自訂訊息時間戳記與格式

處理時區問題通常是開發者的惡夢。當你的 bot 同時服務全球不同地區的使用者，而你的伺服器又跑在 UTC 時，要搞清楚「現在到底是幾點」或是「這則訊息是多久前傳的」真的會讓人抓狂。

OpenClaw 幫你把這些時間戳記標準化，讓模型看到的參考時間始終如一，不再為了換算時間而困惑。

時區

OpenClaw 標準化了時間戳記，讓模型看到統一的參考時間。

訊息外殼（預設為本地時間）

傳入的訊息會被包裝在這樣的外殼（envelope）中：

[Provider ... 2026-01-05 16:26 PST] message text

外殼中的時間戳記預設使用主機本地時間，精確到分鐘。

你可以透過以下配置來覆寫這個設定：

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

• envelopeTimezone: "utc" 使用 UTC 時間。
• envelopeTimezone: "user" 使用 agents.defaults.userTimezone（如果未設定則退回到主機時區）。
• 使用明確的 IANA 時區（例如 "Europe/Vienna"）來設定固定偏移量。
• envelopeTimestamp: "off" 會從外殼標頭中移除絕對時間戳記。
• envelopeElapsed: "off" 會移除經過時間的後綴（例如 +2m 這種格式）。

範例

本地時間（預設）：

[Signal Alice +1555 2026-01-18 00:19 PST] hello

固定時區：

[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello

經過時間：

[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up

Tool 負載（原始 Provider 數據 + 標準化欄位）

Tool 呼叫（例如 channels.discord.readMessages、channels.slack.readMessages 等）會回傳原始的 Provider 時間戳記。為了保持一致性，我們也會加上標準化欄位：

• timestampMs (UTC epoch 毫秒)
• timestampUtc (ISO 8601 UTC 字串)

原始的 Provider 欄位會被保留。

System Prompt 中的使用者時區

設定 agents.defaults.userTimezone 可以告訴模型使用者的本地時區。如果沒有設定，OpenClaw 會在執行時自動解析主機時區（不會寫入配置）。

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

System Prompt 會包含：

• Current Date & Time 區塊，顯示本地時間與時區
• Time format: 12-hour 或 24-hour

你可以透過 agents.defaults.timeFormat (auto | 12 | 24) 來控制 Prompt 的格式。

關於完整的行為與範例，請參考 Date & Time。

相關內容

• Heartbeat — 活躍時段使用時區進行排程
• Cron Jobs — Cron 表達式使用時區進行排程
• Date & Time — 完整的日期與時間行為及範例

---

下一步：

• 想要自動化任務？看看 Cron Jobs 如何設定。
• 深入了解 Date & Time 的詳細運作邏輯。

有任何設定上的疑問嗎？歡迎詢問 AI Setup Assistant！