Summary

• Problem: OpenClaw only supported a single global agents.defaults.userTimezone, so multi-agent setups could not give different agents correct local time context.
• Why it matters: Agent-local time affects system prompt time context, heartbeat active-hours, session status, envelope timestamps, system event timestamps, and time-based helper prompts like memory flush/post-compaction context.
• What changed: Added agents.list[].userTimezone, introduced shared agent-aware timezone resolution, threaded agentId through the relevant call sites, validated configured IANA timezones in schema, and added tests/docs for the new behavior.
• What did NOT change (scope boundary): This does not change timeFormat per agent, host timezone fallback behavior, or explicit non-user timezone settings such as fixed IANA/UTC/local envelope config.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Feature]: Support setting userTimezone per agent openclaw/openclaw#39579

User-visible / Behavior Changes

• New optional config: agents.list[].userTimezone.
• When set, the active agent's userTimezone now overrides agents.defaults.userTimezone.
• This per-agent timezone is now used for:
  • system prompt time context
  • session_status time line
  • heartbeat activeHours.timezone: "user"
  • "user" envelope timestamps
  • "user" system-event timestamps
  • cron-style current-time injection used by memory flush and post-compaction context
• If no per-agent value is set, behavior remains: agents.defaults.userTimezone then host timezone fallback.
• Config validation now rejects invalid IANA timezone strings for both default and per-agent userTimezone.

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: Linux
• Runtime/container: podman
• Model/provider: N/A
• Integration/channel (if any): gateway + multi-agent config; verified via user testing
• Relevant config (redacted):

  {
    agents: {
      defaults: {
        userTimezone: "America/New_York",
        envelopeTimezone: "user",
      },
      list: [
        {
          id: "work",
          userTimezone: "America/Los_Angeles",
        },
      ],
    },
  }

Steps

1. Configure agents.defaults.userTimezone and a different agents.list[].userTimezone for a non-default agent.
2. Run flows using that agent, including session status, prompt/time injection paths, and any envelope/system-event path using "user" timezone.
3. Observe the active agent uses its own timezone instead of the global default.

Expected

• The active agent consistently uses its own userTimezone override everywhere "user" timezone semantics are intended.

Actual

• Before this change, the default/global timezone was used even for non-default agents.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Multi-agent config with different default/per-agent timezones
  • User-visible behavior manually tested as a user
  • Full local validation: pnpm build && pnpm check && pnpm test
• Edge cases checked:
  • Agent without override falls back to agents.defaults.userTimezone
  • No configured timezone falls back to host timezone
  • Invalid configured timezones are rejected by schema validation
  • Envelope/system-event "user" timezone paths receive the active agentId
• What you did not verify:
  • Every external channel manually end-to-end in a live environment

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) Yes
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:
  • Optional only: add agents.list[].userTimezone where agent-specific timezone behavior is desired.

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Remove per-agent userTimezone entries and rely on agents.defaults.userTimezone or revert this PR.
• Files/config to restore:
  • Agent timezone config in agents.list[]
• Known bad symptoms reviewers should watch for:
  • Non-default agents showing the default timezone in prompts, envelopes, heartbeat windows, or status output
  • "user" timezone behavior not varying by agent

Risks and Mitigations

• Risk: A call site using "user" timezone semantics could miss passing agentId and silently fall back to the default timezone.
  • Mitigation: Updated the shared helpers/call sites across gateway, envelope, heartbeat, memory flush, post-compaction context, and system events; added targeted tests.
• Risk: Rejecting invalid timezone strings at schema level could break previously accepted but incorrect configs.
  • Mitigation: This is intentional fail-fast validation; docs and tests cover the accepted IANA-only behavior.

AI Assistance

This PR was AI-assisted using GPT-5.4 and Gemini 3.1 Pro.