Docker: add OPENCLAW_TZ timezone support by Lanfei · Pull Request #34119 · openclaw/openclaw

Lanfei · 2026-03-04T07:36:05Z

Summary

Problem: Docker containers inherit the daemon's timezone (usually UTC), with no way to override it per-deployment.
Why it matters: Users in non-UTC timezones see incorrect timestamps in logs and agent output.
What changed: Added OPENCLAW_TZ env var (IANA format, e.g. Asia/Shanghai); docker-setup.sh reads it and writes it to .env; docker-compose.yml maps it to the standard TZ variable in both openclaw-gateway and openclaw-cli.
What did NOT change: Default behavior is unchanged — if OPENCLAW_TZ is unset, containers continue to use UTC.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #

User-visible / Behavior Changes

New optional env var OPENCLAW_TZ (IANA timezone string). Usage:

OPENCLAW_TZ=Asia/Shanghai ./docker-setup.sh

When set, both gateway and CLI containers will use the specified timezone. When unset, behavior is identical to before (UTC).

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Repro + Verification

Environment

OS:
Runtime/container:
Model/provider:
Integration/channel (if any):
Relevant config (redacted):

Steps

OPENCLAW_TZ=Asia/Shanghai ./docker-setup.sh
Verify .env contains OPENCLAW_TZ=Asia/Shanghai
docker compose exec openclaw-gateway date — should show Shanghai time

Expected

Container date output reflects the configured timezone

Actual

Evidence

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

Human Verification (required)

Verified scenarios:
Edge cases checked:
What you did not verify:

Compatibility / Migration

Backward compatible? Yes
Config/env changes? Yes — new optional OPENCLAW_TZ var; no action needed for existing deployments
Migration needed? No

Failure Recovery (if this breaks)

How to disable/revert this change quickly: Remove OPENCLAW_TZ from .env and redeploy
Files/config to restore: .env, docker-compose.yml
Known bad symptoms: Containers fail to start if an invalid IANA timezone string is supplied

Risks and Mitigations

None.

greptile-apps · 2026-03-04T07:38:34Z

Greptile Summary

This PR adds an optional OPENCLAW_TZ environment variable that is wired through docker-setup.sh into .env and mapped to the standard TZ variable inside both openclaw-gateway and openclaw-cli containers. The implementation is minimal and follows the existing patterns for optional env vars in the script.

Key points:

When OPENCLAW_TZ is unset, the TZ: ${OPENCLAW_TZ:-} expansion in docker-compose.yml always injects TZ= (empty string) into containers rather than leaving TZ absent. In glibc/musl an empty TZ is treated as UTC, which matches the stated intent, but it differs subtly from a fully absent TZ and would silently override a custom /etc/localtime in non-standard images.
TIMEZONE / OPENCLAW_TZ is the only user-supplied string written to .env that is not checked by contains_disallowed_chars. A value with an embedded newline could split into two lines in .env and inject an extra key, consistent with how newlines affect other variables that are validated earlier in the script.

Confidence Score: 4/5

Safe to merge with minor improvements suggested around input validation and empty-TZ behavior.
The change is small, backward-compatible, and correctly wires the new variable end-to-end. The two flagged issues are both style/best-practice concerns rather than blocking bugs — no runtime errors are introduced for the common case.
docker-setup.sh (missing validation for OPENCLAW_TZ), docker-compose.yml (empty TZ= vs absent TZ)

_{Last reviewed commit: 8b502a8}

docker-compose.yml

docker-setup.sh

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8b502a86fa

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

docker-compose.yml

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6aaa1fb980

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

docker-compose.yml

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e13dea42b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

docker-setup.sh

Lanfei · 2026-03-13T07:01:18Z

Hey @jalehman @obviyus — could you take a look when you have a moment? CI is green and the change is small. I currently have several open PRs waiting for review, which is making it hard for me to continue contributing. Any feedback or a quick merge would be much appreciated. Thanks!

obviyus · 2026-03-13T09:22:09Z

Landed on main.

Landed source commit: 393280e
Merge commit: 4d3a2f6

Thanks @Lanfei.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 393280e7de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-13T09:25:47Z

docker-compose.yml

      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+      TZ: ${OPENCLAW_TZ:-UTC}


Preserve image default timezone when OPENCLAW_TZ is unset

Setting TZ: ${OPENCLAW_TZ:-UTC} forces every container to run in UTC even when no override was requested, which changes behavior for deployments that use OPENCLAW_IMAGE with a non-UTC image default (for example an image with /etc/localtime set). Before this change, leaving timezone unset let the image decide; now those deployments silently shift all “local time” formatting to UTC.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-13T09:25:47Z

docker-setup.sh


+is_valid_timezone() {
+  local value="$1"
+  [[ -e "/usr/share/zoneinfo/$value" && ! -d "/usr/share/zoneinfo/$value" ]]


Avoid host-coupled timezone validation for OPENCLAW_TZ

is_valid_timezone rejects values unless they exist under the host path /usr/share/zoneinfo, so docker-setup.sh can fail on hosts without that database layout (or with stale tzdata) even when the target container would accept the timezone. This makes the new OPENCLAW_TZ feature unusable in those environments because setup aborts before writing .env/starting compose.

Useful? React with 👍 / 👎.

* main: (168 commits) fix: stabilize macos daemon onboarding fix(ui): keep shared auth on insecure control-ui connects (openclaw#45088) docs(plugins): clarify workspace shadowing fix(node-host): harden perl approval binding fix(node-host): harden pnpm approval binding fix(discovery): add missing domain to wideArea Zod config schema (openclaw#35615) chore(gitignore): add docker-compose override (openclaw#42879) feat(ios): add onboarding welcome pager (openclaw#45054) fix(signal): add groups config to Signal channel schema (openclaw#27199) fix: restore web fetch firecrawl config in runtime zod schema (openclaw#42583) fix: polish Android QR scanner onboarding (openclaw#45021) fix(android): use Google Code Scanner for onboarding QR fix(config): add missing params field to agents.list[] validation schema (openclaw#41171) docs(contributing): update Android app ownership fix(agents): rephrase session reset prompt to avoid Azure content filter (openclaw#43403) test(config): cover requiresOpenAiAnthropicToolPayload in compat schema fixture fix(agents): respect explicit user compat overrides for non-native openai-completions (openclaw#44432) Android: fix HttpURLConnection leak in TalkModeVoiceResolver (openclaw#43780) Docker: add OPENCLAW_TZ timezone support (openclaw#34119) fix(agents): avoid injecting memory file twice on case-insensitive mounts (openclaw#26054) ...

@Lanfei

* Docker: add OPENCLAW_TZ timezone support * fix: validate docker timezone names * fix: support Docker timezone override (openclaw#34119) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

@Lanfei

* Docker: add OPENCLAW_TZ timezone support * fix: validate docker timezone names * fix: support Docker timezone override (openclaw#34119) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

New in v2026.3.13 (PR openclaw/openclaw#34119), maps to TZ inside the container so logs and Date output match the configured timezone. Ref #669 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

@Lanfei

* Docker: add OPENCLAW_TZ timezone support * fix: validate docker timezone names * fix: support Docker timezone override (openclaw#34119) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]> (cherry picked from commit 4d3a2f6)

@Lanfei

* Docker: add OPENCLAW_TZ timezone support * fix: validate docker timezone names * fix: support Docker timezone override (openclaw#34119) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

openclaw-barnacle bot added docker Docker and sandbox tooling size: XS labels Mar 4, 2026

greptile-apps bot reviewed Mar 4, 2026

View reviewed changes

docker-compose.yml Outdated Show resolved Hide resolved

docker-setup.sh Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

docker-compose.yml Outdated Show resolved Hide resolved

Lanfei force-pushed the docker/timezone-support branch from 5ecd234 to 6aaa1fb Compare March 4, 2026 07:50

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

docker-compose.yml Outdated Show resolved Hide resolved

Lanfei force-pushed the docker/timezone-support branch 2 times, most recently from 815b0e7 to 6e13dea Compare March 4, 2026 08:06

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

docker-setup.sh Outdated Show resolved Hide resolved

Lanfei force-pushed the docker/timezone-support branch from 6e13dea to a72c010 Compare March 4, 2026 08:51

openclaw-barnacle bot added size: S and removed size: XS labels Mar 13, 2026

Lanfei and others added 3 commits March 13, 2026 14:48

Docker: add OPENCLAW_TZ timezone support

f15c85c

fix: validate docker timezone names

f4dc00e

fix: support Docker timezone override (openclaw#34119) (thanks @Lanfei)

393280e

obviyus force-pushed the docker/timezone-support branch from f3f391b to 393280e Compare March 13, 2026 09:19

obviyus merged commit 4d3a2f6 into openclaw:main Mar 13, 2026
28 of 29 checks passed

chatgpt-codex-connector bot reviewed Mar 13, 2026

View reviewed changes

github-actions bot mentioned this pull request Mar 13, 2026

📡 Upstream Digest — 2026-03-13 10:28 UTC curtismercier/openclaw-mods#251

Open

Lanfei deleted the docker/timezone-support branch March 14, 2026 02:20

github-actions bot mentioned this pull request Mar 15, 2026

📢 OpenClaw 新版本发布: v2026.3.13-1 xianyu110/awesome-openclaw-tutorial#32

Closed

5 tasks

obviyus self-assigned this Mar 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Docker: add OPENCLAW_TZ timezone support#34119

Docker: add OPENCLAW_TZ timezone support#34119
obviyus merged 3 commits intoopenclaw:mainfrom
Lanfei:docker/timezone-support

Lanfei commented Mar 4, 2026

Uh oh!

greptile-apps bot commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Lanfei commented Mar 13, 2026

Uh oh!

Uh oh!

obviyus commented Mar 13, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Lanfei commented Mar 4, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

greptile-apps bot commented Mar 4, 2026

Greptile Summary

Confidence Score: 4/5

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Lanfei commented Mar 13, 2026

Uh oh!

Uh oh!

obviyus commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

obviyus commented Mar 13, 2026 •

edited

Loading