时区

Timezone（时区）配置让 Agent 具有正确的时间感知能力。OpenClaw 使用 IANA 时区格式，影响系统提示词中的时间、Cron 任务调度和会话重置。

Agent 时区设置

每个 Agent 可以配置独立的时区：

# Agent 配置
timezone: Asia/Shanghai         # 北京时间 (UTC+8)

IANA 时区格式

OpenClaw 使用 IANA 时区标识符（也称 TZ Database），格式为 区域/城市。请勿使用 UTC+8 或 CST 等缩写格式。

常用时区标识

时区	IANA 标识	UTC 偏移
北京/上海	Asia/Shanghai	UTC+8
香港	Asia/Hong_Kong	UTC+8
台北	Asia/Taipei	UTC+8
东京	Asia/Tokyo	UTC+9
首尔	Asia/Seoul	UTC+9
新加坡	Asia/Singapore	UTC+8
纽约	America/New_York	UTC-5/4
旧金山	America/Los_Angeles	UTC-8/7
伦敦	Europe/London	UTC+0/1
柏林	Europe/Berlin	UTC+1/2

夏令时

IANA 时区自动处理夏令时（DST）切换。例如 America/New_York 在冬季为 UTC-5，夏季为 UTC-4。

时区影响的功能

系统提示词中的时间

Agent 的系统提示词会注入基于配置时区的当前时间：

# 系统提示词中的时间段
Current date and time: 2025-01-15 14:30:00 (Asia/Shanghai, UTC+8)

session_status 工具也返回时区感知的时间：

{
  "currentTime": "2025-01-15T14:30:00+08:00",
  "timezone": "Asia/Shanghai"
}

Cron 定时任务

Cron 表达式按照配置的时区执行：

timezone: Asia/Shanghai

cron:
  - schedule: "0 9 * * *"       # 每天上午 9 点（北京时间）
    action: daily-summary
    
  - schedule: "30 18 * * 1-5"   # 工作日下午 6:30（北京时间）
    action: end-of-day-report

Cron 时区

Cron 任务使用 Agent 级别的 timezone 配置。如果不设置，默认使用服务器的系统时区。

会话重置

定时会话重置受时区影响：

timezone: Asia/Shanghai

sessionReset:
  daily: "04:00"               # 每天凌晨 4 点（北京时间）重置

如果 timezone: Asia/Shanghai 且 daily: "04:00"
则实际重置时间为 UTC 20:00 (前一天)

如果 timezone: America/New_York 且 daily: "04:00"
则实际重置时间为 UTC 09:00 (冬) / UTC 08:00 (夏)

每日记忆日志

记忆日志的日期分界也基于时区：

timezone: Asia/Shanghai

1月15日 23:59 → 写入 memory/2025-01-15.md
1月16日 00:01 → 写入 memory/2025-01-16.md

多时区 Agent

不同 Agent 可以配置不同的时区：

agents:
  - name: china-support
    timezone: Asia/Shanghai
    
  - name: us-support
    timezone: America/New_York
    
  - name: eu-support
    timezone: Europe/Berlin

全球部署

为不同地区的用户配置对应时区的 Agent，确保 Cron 任务和会话重置在各地区的本地时间执行。

默认时区

如果未配置时区，OpenClaw 按以下优先级确定：

1. Agent 配置中的 timezone       (最高优先级)
2. 环境变量 TZ
3. 服务器系统时区
4. UTC                           (最后兜底)

# 通过环境变量设置默认时区
export TZ="Asia/Shanghai"

时区验证

OpenClaw 在启动时验证时区配置：

# 检查时区配置
openclaw config check

# 输出：
# ✅ timezone: Asia/Shanghai (valid)
# ⏰ Current time: 2025-01-15 14:30:00 CST
# 📅 Next cron: daily-summary at 2025-01-16 09:00:00 CST

无效时区

如果配置了无效的时区标识（如 Beijing 或 UTC+8），OpenClaw 会在启动时报错并回退到 UTC。

配置示例

# 完整时区相关配置
timezone: Asia/Shanghai

cron:
  - schedule: "0 9 * * *"
    action: daily-summary
  - schedule: "0 22 * * *"
    action: daily-memory-cleanup

sessionReset:
  daily: "04:00"

# 日志时间戳也使用配置的时区
logging:
  timestampTimezone: true

🇨🇳 中国用户须知

• 中国大陆统一使用 Asia/Shanghai（无夏令时）
• 香港用户使用 Asia/Hong_Kong
• 台湾用户使用 Asia/Taipei
• 所有 Cron 时间均为北京时间，无需额外转换

下一步

• 了解 会话管理 中时区对会话重置的影响
• 查看 系统提示词 了解时间注入
• 探索 功能总览 中的 Cron 自动化功能