OpenClaw 時間與時區設定指南

處理不同時區的訊息標籤（timestamps）一直都是開發者的噩夢。當你的伺服器、使用者和通訊軟體 Provider 都在不同的時區時，訊息顯示的時間往往會讓你感到混亂，甚至導致邏輯判斷錯誤。

OpenClaw 預設在傳輸時間標籤上使用 host-local time（主機本地時間），而 user timezone（使用者時區）則僅用於 System Prompt。這能確保工具保留其原生語義，同時讓你清楚掌握訊息發生的時間。

需要準備的東西

• OpenClaw 配置文件
• 支援的通訊管道（如 WhatsApp, Slack, Discord, Telegram）

快速開始

OpenClaw 的訊息外殼（Message envelopes）預設會帶上分鐘精度的時間標籤，格式如下：

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

你可以透過設定檔來自定義這個行為，例如更改時區或關閉特定顯示：

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // 可選 "utc" | "local" | "user" 或 IANA 時區字串
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

常用設定範例

• 使用使用者時區：將 envelopeTimezone 設為 "user"，它會抓取 agents.defaults.userTimezone 的設定。
• 固定時區：直接填入 IANA 字串，例如 "America/Chicago"。
• 關閉時間顯示：將 envelopeTimestamp 設為 "off" 即可移除標頭中的絕對時間。
• 顯示經過時間：開啟 envelopeElapsed 後，你會看到類似 +30s 的相對時間後綴。

系統提示詞與事件

為了讓 Prompt Caching 保持穩定，OpenClaw 在 System Prompt 中只會加入時區名稱，而不會放入會隨秒數變動的具體時間點：

Time zone: America/Chicago

如果你的 Agent 需要知道精確的當前時間，請呼叫 session_status 工具，狀態卡片中會包含完整的時間標籤。

此外，系統事件（如 Model switched）也會使用與訊息外殼相同的時區設定：

System: [2026-01-12 12:19:17 PST] Model switched.

配置使用者時區與格式

你可以在 defaults 中指定使用者的偏好：

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago",
      timeFormat: "auto", // 可選 auto | 12 | 24
    },
  },
}

當 timeFormat 設為 auto 時，OpenClaw 會自動偵測 macOS 或 Windows 的系統偏好，並將結果快取起來以節省效能。

API 與工具回傳格式

當你使用 Channel 工具時，OpenClaw 會保留 Provider 原生的時間欄位，並額外加上標準化的欄位，方便你進行後續處理：

• timestampMs: Epoch 毫秒數 (UTC)
• timestampUtc: ISO 8601 UTC 字串

無論是 Slack 的字串格式、Discord 的 ISO 格式，還是 Telegram/WhatsApp 的數值格式，你都能透過這兩個標準欄位取得一致的時間數據。

疑難排解

• Agent 拿到的時間不準？ 請檢查你的 userTimezone 設定。如果 Agent 需要獲取當前時間，請確保它有權限使用 session_status 工具，而不是只依賴 System Prompt。

• 自動偵測時間格式失敗？ 當 timeFormat 設為 auto 時，OpenClaw 會嘗試讀取 OS 設定。如果抓不到，它會回退（fallback）到語系預設格式。

想要更快速地完成設定嗎？試試我們的 AI Setup Assistant。

下一步

• System Prompt
• Timezones
• Messages