Timezones

기준일: 2026-07-26
공식 기준: Timezones

Timezones 문서는 OpenClaw 공식 문서(concepts/timezone)를 한국어로 정리한 가이드입니다. Where timezones show up in OpenClaw — envelopes, tool payloads, system prompt 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Where timezones show up in OpenClaw — envelopes, tool payloads, system prompt

한국어 가이드 범위: concepts/timezone 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Three timezone surfaces
• Setting the user timezone
• Envelope timezone values
• When to override
• 관련 문서

상세 내용

본문

OpenClaw standardizes timestamps so the model sees a single reference time instead of a mix of provider-local clocks. Three surfaces show timezones, each with its own purpose:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Three timezone surfaces

The system prompt deliberately omits the live clock to keep prompt caching stable across turns. When the agent needs the current time, it calls session_status.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Surface	What it shows	Default	Configured via
Message envelopes	Wraps inbound channel messages: [Signal +1555 Sun 2026-01-18 00:19:42 PST] hello	Host-local	agents.defaults.envelopeTimezone
Tool payloads	Channel readMessages-style tools return raw provider time plus normalized timestampMs / timestampUtc	UTC fields always present	Not configurable; preserves provider-native timestamps
System prompt	A small Current Date & Time block with the time zone only (no clock value, for cache stability)	Host timezone if userTimezone unset	agents.defaults.userTimezone

Setting the user timezone

If userTimezone is unset, OpenClaw resolves the host timezone at runtime via Intl.DateTimeFormat().resolvedOptions().timeZone (no config write). agents.defaults.timeFormat (auto | 12 | 24) controls 12h/24h rendering in envelopes and downstream surfaces, not in the system prompt section.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Envelope timezone values

agents.defaults.envelopeTimezone accepts:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• "local" (default) or "host" - host machine's timezone.
• "utc" or "gmt" - UTC.
• "user" - the resolved agents.defaults.userTimezone (falls back to host timezone if unset).
• Any explicit IANA zone string, e.g. "Europe/Vienna".

When to override

For the full behavior reference, examples per provider, and elapsed-time formatting, see Date & Time.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Use "utc" for stable timestamps across hosts in different regions, or to match UTC-aligned diagnostics/log output.
• Use "user" to keep envelopes aligned with the configured user timezone regardless of which zone the gateway host runs in.
• Use a fixed IANA zone when the gateway host is in one zone but the envelope should always read in another zone regardless of host migration.
• Set envelopeTimestamp: "off" when timestamp context is not useful for the conversation. This removes absolute timestamps from envelopes, direct agent prompt prefixes, and embedded model-input prefixes.

관련 문서

주요 항목:

• Date & Time - full envelope/tool/prompt behavior and examples.
• Heartbeat - active hours use timezone for scheduling.
• Cron Jobs - cron expressions use timezone for scheduling.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/timezone
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

관련 링크

• 공식 원문: concepts/timezone
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.