---
read_when:
    - 시간대 처리를 빠르게 이해할 수 있는 개념 모델이 필요합니다
    - 시간대를 어디에 설정하거나 재정의할지 결정하고 있습니다
summary: OpenClaw에서 시간대가 표시되는 위치 — 엔벌로프, 도구 페이로드, 시스템 프롬프트
title: 시간대
x-i18n:
    generated_at: "2026-06-27T17:26:04Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: cc5bfe595c81b9c6ffaceac4c86b6f82b82917a506cdd7227e3e8cb1c0eb99a3
    source_path: concepts/timezone.md
    workflow: 16
---

OpenClaw는 타임스탬프를 표준화하여 모델이 제공자별 로컬 시계가 섞인 값 대신 **단일 기준 시간**을 보도록 합니다. 시간대가 나타나는 표면은 세 가지이며, 각각 고유한 목적이 있습니다.

## 세 가지 시간대 표면

| 표면              | 표시 내용                                                                                              | 기본값                                | 설정 방법                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- |
| 메시지 엔벨로프   | 인바운드 채널 메시지를 래핑합니다: `[Signal +1555 Sun 2026-01-18 00:19:42 PST] hello`                  | 호스트 로컬                           | `agents.defaults.envelopeTimezone`                      |
| 도구 페이로드     | 채널 `readMessages` 스타일 도구는 원시 제공자 시간 + 정규화된 `timestampMs` / `timestampUtc`를 반환합니다 | UTC 필드는 항상 존재                  | 설정 불가 — 제공자 네이티브 타임스탬프를 보존합니다     |
| 시스템 프롬프트   | **시간대만** 포함하는 작은 `현재 날짜 및 시간` 블록입니다(캐시 안정성을 위해 시계 값 없음)            | `userTimezone`이 설정되지 않으면 호스트 시간대 | `agents.defaults.userTimezone`                          |

시스템 프롬프트는 턴 간 프롬프트 캐싱을 안정적으로 유지하기 위해 의도적으로 실시간 시계를 생략합니다. 에이전트가 현재 시간이 필요하면 `session_status`를 호출합니다.

## 사용자 시간대 설정

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

`userTimezone`이 설정되지 않으면 OpenClaw는 런타임에 호스트 시간대를 확인합니다(설정 쓰기 없음). `agents.defaults.timeFormat`(`auto` | `12` | `24`)은 엔벨로프와 다운스트림 표면의 12시간/24시간 표시를 제어하며, 시스템 프롬프트 섹션에는 적용되지 않습니다.

## 재정의해야 하는 경우

- 서로 다른 지역의 호스트 간에 안정적인 타임스탬프가 필요하거나, UTC 기준 로그를 진단 출력과 맞추고 싶을 때는 **UTC 엔벨로프**(`envelopeTimezone: "utc"`)를 사용하세요.
- Gateway 호스트는 한 시간대에 있지만 사용자는 다른 시간대에 있으며, 호스트 마이그레이션과 관계없이 엔벨로프를 사용자 시간대로 읽히게 하려면 **고정 IANA 시간대**(예: `"Europe/Vienna"`)를 사용하세요.
- 타임스탬프 컨텍스트가 대화에 유용하지 않을 때는 **`envelopeTimestamp: "off"` 설정**을 사용하세요. 그러면 엔벨로프, 직접 에이전트 프롬프트 접두사, 임베드된 모델 입력 접두사에서 절대 타임스탬프가 제거됩니다.

전체 동작 참조, 제공자별 예시, 경과 시간 형식은 [날짜 및 시간](/ko/date-time)을 참조하세요.

## 관련 항목

- [날짜 및 시간](/ko/date-time) — 전체 엔벨로프/도구/프롬프트 동작과 예시.
- [Heartbeat](/ko/gateway/heartbeat) — 활성 시간은 예약에 시간대를 사용합니다.
- [Cron 작업](/ko/automation/cron-jobs) — Cron 표현식은 예약에 시간대를 사용합니다.