OpenClaw 타임존 설정 가이드: 메시지 타임스탬프 최적화

여러 지역의 사용자를 대상으로 하는 AI 서비스를 개발하다 보면 타임존 처리가 정말 까다롭죠. 서버 시간과 사용자 시간이 꼬여서 엉뚱한 시간에 알림이 가거나 로그 분석이 힘들어지는 경우도 많고요.

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 값을 사용해요 (설정이 없으면 호스트 타임존으로 돌아갑니다).
• 특정 지역의 고정된 오프셋을 사용하려면 "Europe/Vienna"와 같은 IANA 타임존 이름을 직접 입력하세요.
• 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

툴 페이로드 (원본 데이터 + 정규화된 필드)

channels.discord.readMessages나 channels.slack.readMessages 같은 툴 호출은 제공업체의 원본 타임스탬프를 반환합니다. 여기에 데이터 일관성을 위해 OpenClaw가 정규화된 필드를 추가로 붙여줘요.

• timestampMs (UTC 기준 밀리초 단위 epoch 시간)
• timestampUtc (ISO 8601 형식의 UTC 문자열)

제공업체의 원본 필드도 그대로 유지되니 안심하고 사용하세요.

시스템 프롬프트를 위한 사용자 타임존

agents.defaults.userTimezone을 설정하면 모델에게 사용자의 로컬 타임존이 어디인지 정확히 알려줄 수 있어요. 만약 이 값을 설정하지 않으면, OpenClaw는 실행 시점에 호스트의 타임존을 자동으로 확인합니다 (설정 파일에 직접 쓰지는 않아요).

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

이렇게 설정하면 시스템 프롬프트에 다음과 같은 정보가 포함됩니다.

• 로컬 시간과 타임존이 포함된 Current Date & Time 섹션
• Time format: 12-hour 또는 24-hour 형식 정보

프롬프트에 표시되는 시간 형식은 agents.defaults.timeFormat (auto | 12 | 24) 옵션으로 제어할 수 있습니다.

전체적인 동작 방식과 더 많은 예시는 Date & Time 문서에서 확인해 보세요.

관련 문서

• Heartbeat — 활성 시간대의 스케줄링에 타임존을 사용합니다.
• Cron Jobs — 크론 표현식의 스케줄링에 타임존을 사용합니다.
• Date & Time — 전체적인 날짜 및 시간 동작 방식과 예시를 다룹니다.

AI Setup Assistant