OpenClaw에서 날짜와 시간 관리하기

여러 지역의 사용자와 상호작용하는 서비스를 개발하다 보면 시간 처리가 정말 까다롭다는 걸 느끼게 돼요. 서버 시간, 사용자 시간, 그리고 각 API가 보내주는 시간이 제각각이라 로그를 분석하거나 메시지 순서를 맞출 때 혼란스러운 경우가 많죠. OpenClaw는 이런 복잡한 시간 처리를 체계적으로 관리할 수 있는 방법을 제공합니다.

필요한 것

• OpenClaw 설정 파일 (json5)
• IANA 시간대 정보 (선택 사항)

빠른 시작

OpenClaw는 기본적으로 호스트 로컬 시간을 타임스탬프에 사용하고, 사용자 시간대는 System prompt에만 적용해요. 5분 안에 설정을 맞춤화하는 방법을 알아볼게요.

1. 메시지 봉투(Envelope) 설정하기

인바운드 메시지는 기본적으로 분 단위의 타임스탬프로 감싸져요. agents.defaults에서 이 동작을 변경할 수 있습니다.

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

• envelopeTimezone: utc, local, user 또는 America/Chicago 같은 IANA 시간대를 직접 지정하세요.
• envelopeElapsed: off로 설정하면 +2m 같은 경과 시간 표시를 제거합니다.

2. 사용자 시간대 및 형식 지정하기

사용자에게 맞는 시간대와 12시간/24시간 형식을 설정하면 Prompt context에 반영됩니다.

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

timeFormat을 auto로 두면 macOS나 Windows 같은 운영체제 설정을 자동으로 확인해서 적용해요.

문제 해결

Prompt caching이 자주 깨지는 문제가 있어요

OpenClaw는 캐싱 효율을 높이기 위해 System prompt에 시/분 정보 없이 시간대(Time zone) 정보만 포함해요. 만약 Agent가 정확한 현재 시간이 필요하다면 session_status Tool을 사용하도록 하세요. Status card에 타임스탬프 라인이 포함되어 있습니다.

Tool에서 가져오는 시간 값이 일관되지 않아요

Channel Tool은 Provider의 네이티브 타임스탬프를 그대로 반환하면서도, 일관성을 위해 다음 필드를 추가로 제공합니다.

• timestampMs: Epoch 밀리초 (UTC)
• timestampUtc: ISO 8601 UTC 문자열

Slack은 Epoch 스타일 문자열을, Discord는 UTC ISO 타임스탬프를 사용하지만 위 필드들을 통해 통일된 방식으로 처리할 수 있습니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• System Prompt
• Timezones
• Messages