OpenClawで日付と時刻を正しく扱う方法

開発者にとって、複数のソースから流れてくるデータの「時刻」を同期させるのは共通の悩みです。サーバーの時刻、ユーザーの居住地の時刻、そして各プラットフォーム独自の形式が混在すると、デバッグやコンテキストの把握が途端に難しくなります。

OpenClawでは、これらの複雑な時刻管理をシンプルに整理するための仕組みが用意されています。

必要なもの

• OpenClawの基本設定ファイル（JSON5形式）
• 設定したいIANAタイムゾーン（例: "America/Chicago" や "Asia/Tokyo"）

Quick Start: 5分でできる基本設定

OpenClawのデフォルト設定では、メッセージのタイムスタンプにホストマシンのローカル時刻が使用されます。これをプロジェクトのニーズに合わせて調整してみましょう。

1. メッセージエンベロープのカスタマイズ

メッセージが届いた際のタイムスタンプ表示を制御できます。agents.defaults セクションで設定を変更します。

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANAタイムゾーン
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

• envelopeTimezone: utc、local（ホスト時刻）、user（ユーザー設定）、または特定のIANA名を指定します。
• envelopeTimestamp: off にすると、絶対時刻の表示を消去できます。

2. ユーザーのタイムゾーンと表示形式の設定

ユーザーに合わせた時刻表示を行うには、以下の設定を追加します。

{
  agents: {
    defaults: {
      userTimezone: "Asia/Tokyo",
      timeFormat: "auto", // auto | 12 | 24
    },
  },
}

timeFormat を auto に設定すると、OS（macOS/Windows）の設定を自動的に検出し、結果をプロセスごとにキャッシュして効率的に動作します。

3. システムプロンプトでの利用

ユーザーのタイムゾーンが設定されている場合、OpenClawはシステムプロンプトにタイムゾーン情報（例: Time zone: Asia/Tokyo）を自動的に含めます。

あえて具体的な時刻を含めないことで、プロンプトキャッシュの安定性を高めています。エージェントが「現在の正確な時刻」を知る必要がある場合は、session_status ツールを使用してください。

4. ツールからのデータ取得

API を通じて取得されるメッセージデータには、プラットフォーム独自の時刻と、正規化されたフィールドの両方が含まれます。

• timestampMs: UNIXエポックミリ秒（UTC）
• timestampUtc: ISO 8601形式のUTC文字列

トラブルシューティング

プロンプトキャッシュが頻繁にリセットされる

システムプロンプトに「現在の時刻（分単位など）」を直接含めてしまうと、キャッシュが効かなくなります。OpenClawはこれを避けるため、プロンプトにはタイムゾーン名のみを記載する設計になっています。時刻が必要な際は必ず session_status ツールを呼び出すようにしてください。

ツールから取得した時刻がローカル時間ではない

SlackやDiscordなどの各コネクタは、API から取得した生の値を保持しつつ、timestampUtc などの正規化されたフィールドを付与します。ローカル時刻が必要な場合は、これらの正規化されたUTCフィールドを元に、アプリケーション側で変換を行ってください。

設定の詳細や特定のユースケースについて質問がある場合は、AI Setup Assistant を活用してください。

次のステップ

• System Prompt
• Timezones
• Messages