openclaw - ✅(Solved) Fix Codex app-server isolated HOME breaks trusted local tool auth; add real-home override [2 pull requests, 1 comments, 2 participants]

openclaw2026-05-10 14:11:17

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#80288•Fetched 2026-05-11 03:16:48

View on GitHub

Comments

Participants

Timeline

Reactions

Author

EthanSK

Participants

clawsweeper[bot]

EthanSK

Timeline (top)

cross-referenced ×2commented ×1mentioned ×1subscribed ×1

OpenClaw's Codex app-server launch path isolates both CODEX_HOME and HOME under the per-agent directory. That is good for agent state isolation, but it breaks trusted local integrations that rely on the real user home, such as gh, Git credential helpers, Agent Bridge config, and other dotfile-backed CLI auth.

In a trusted local deployment, the desired split is:

keep CODEX_HOME isolated per OpenClaw agent, so Codex skills/plugins/config/thread state do not leak between agents
allow the spawned Codex app-server process to use the real OS user HOME, so normal local CLI auth and config continue to work

Error Message

The spawned Codex app-server process was running with a HOME like:

Root Cause

This breaks more than GitHub. Any local tool that expects real-home config can fail or appear logged out/misconfigured when called from the Codex app-server runtime.

Fix Action

Fix / Workaround

A local prototype patch added support for:

A local source patch validated the approach with targeted Codex app-server config/auth tests, schema checks, and a live wrapper rollout across local Mac, MBP, and Windows gateways.

The live-compatible wrapper workaround is currently in use, but first-class config support would avoid requiring wrapper scripts per machine.

PR fix notes

PR #80315: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Repository: openclaw/openclaw
Author: hclsys
State: closed | merged: False
Link: https://github.com/openclaw/openclaw/pull/80315

Description (problem / solution / changelog)

Summary

Adds plugins.entries.codex.config.appServer.homeDir config key and OPENCLAW_CODEX_APP_SERVER_HOME_DIR env fallback. When set, the Codex app-server process receives the configured path as HOME so local CLI auth (gh, Git credential helpers, Agent Bridge config, and other dotfile-backed integrations) continues to work. CODEX_HOME remains isolated under the per-agent directory.

Closes #80288

Changes

extensions/codex/src/app-server/config.ts

Add homeDir?: string to CodexAppServerStartOptions type
Add homeDir?: string to CodexPluginConfig.appServer shape
Add "homeDir" to CODEX_APP_SERVER_CONFIG_KEYS (keeps config key array in sync with manifest schema test)
Read config.homeDir ?? env.OPENCLAW_CODEX_APP_SERVER_HOME_DIR in resolveCodexAppServerRuntimeOptions and pass it through to start

extensions/codex/src/app-server/auth-bridge.ts

In withAgentCodexHomeEnvironment: use startOptions.homeDir as the resolved HOME when set (explicit env.HOME still takes priority, preserving existing override semantics). Skip mkdir for the native home dir when a real-home override is provided (the real home already exists).

extensions/codex/openclaw.plugin.json

Add homeDir property to configSchema.properties.appServer.properties
Add appServer.homeDir UI hint with label and help text

Real behavior proof

behavior: withAgentCodexHomeEnvironment now uses startOptions.homeDir as HOME while keeping CODEX_HOME isolated under <agentDir>/codex-home

environment: Ubuntu 22.04 (DGX Spark), Node 22, vitest 4.1.5

steps:

Call bridgeCodexAppServerStartOptions with startOptions = { homeDir: os.homedir(), ... }
Observe the resulting env.HOME and env.CODEX_HOME

evidence:

 Test Files  2 passed (2)
      Tests  70 passed (70)
   Duration  7.34s

New test: "uses homeDir as HOME while keeping CODEX_HOME isolated" — asserts env.CODEX_HOME is the per-agent codex-home dir and env.HOME equals os.homedir().

observedResult: env.CODEX_HOME = <agentDir>/codex-home, env.HOME = /home/chenglunhu (real OS home). 70/70 tests pass including 30 auth-bridge tests and 40 config tests.

notTested: Live Codex app-server spawn with real gh auth status verification; WebSocket transport (homeDir is stdio-only concern via withAgentCodexHomeEnvironment).

Changed files

extensions/codex/openclaw.plugin.json (modified, +8/-0)
extensions/codex/src/app-server/auth-bridge.test.ts (modified, +15/-0)
extensions/codex/src/app-server/auth-bridge.ts (modified, +6/-2)
extensions/codex/src/app-server/config.ts (modified, +7/-0)

PR #80318: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Repository: openclaw/openclaw
Author: hclsys
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/80318

Description (problem / solution / changelog)

Summary

Closes #80288

Changes

extensions/codex/src/app-server/config.ts

Add homeDir?: string to CodexAppServerStartOptions type
Add homeDir?: string to CodexPluginConfig.appServer shape
Add "homeDir" to CODEX_APP_SERVER_CONFIG_KEYS
Read config.homeDir ?? env.OPENCLAW_CODEX_APP_SERVER_HOME_DIR in resolveCodexAppServerRuntimeOptions

extensions/codex/src/app-server/auth-bridge.ts

In withAgentCodexHomeEnvironment: use startOptions.homeDir as HOME when set (explicit env.HOME still takes priority). Skip mkdir for the native home dir when using a real-home override.

extensions/codex/openclaw.plugin.json

Add homeDir property to configSchema.properties.appServer.properties
Add appServer.homeDir UI hint

Real behavior proof

Behavior or issue addressed: withAgentCodexHomeEnvironment now accepts startOptions.homeDir as the resolved HOME while keeping CODEX_HOME isolated under <agentDir>/codex-home. Without this, Codex app-server processes run with a synthetic HOME that breaks local CLI auth tools like gh.

Real environment tested: Ubuntu 22.04 (DGX Spark), Node 22.x, vitest 4.1.5

Exact steps or command run after this patch:

node scripts/test-projects.mjs extensions/codex/src/app-server/auth-bridge.test.ts
node scripts/test-projects.mjs extensions/codex/src/app-server/config.test.ts

Evidence: Terminal output from node scripts/test-projects.mjs extensions/codex/src/app-server/auth-bridge.test.ts:

 Test Files  1 passed (1)
      Tests  30 passed (30)
   Start at  23:29:58
   Duration  14.04s (transform 8.27s, setup 233ms, import 10.12s, tests 3.61s, environment 0ms)

New test: "uses homeDir as HOME while keeping CODEX_HOME isolated" (auth-bridge.test.ts) — asserts result.env.CODEX_HOME === <agentDir>/codex-home and result.env.HOME === os.homedir() when startOptions.homeDir is set. Config test: node scripts/test-projects.mjs extensions/codex/src/app-server/config.test.ts → 40 passed including the manifestKeys sync test.

Observed result after fix: env.CODEX_HOME = <agentDir>/codex-home, env.HOME = /home/chenglunhu (real OS home). 70/70 tests pass (30 auth-bridge + 40 config).

What was not tested: Live Codex app-server spawn with real gh auth status verification; WebSocket transport (homeDir applies to stdio spawn path via withAgentCodexHomeEnvironment).

Changed files

extensions/codex/openclaw.plugin.json (modified, +8/-0)
extensions/codex/src/app-server/auth-bridge.test.ts (modified, +15/-0)
extensions/codex/src/app-server/auth-bridge.ts (modified, +6/-2)
extensions/codex/src/app-server/config.ts (modified, +7/-0)

Code Example

~/.openclaw/agents/main/agent/codex-home/home

---

plugins.entries.codex.config.appServer.homeDir

---

OPENCLAW_CODEX_APP_SERVER_HOME_DIR

RAW_BUFFERClick to expand / collapse

Summary

In a trusted local deployment, the desired split is:

keep CODEX_HOME isolated per OpenClaw agent, so Codex skills/plugins/config/thread state do not leak between agents
allow the spawned Codex app-server process to use the real OS user HOME, so normal local CLI auth and config continue to work

Observed behavior

The spawned Codex app-server process was running with a HOME like:

~/.openclaw/agents/main/agent/codex-home/home

That made direct gh auth status and other real-home config look missing even though the user was still correctly authenticated in the actual OS account home.

Why this matters

This breaks more than GitHub. Any local tool that expects real-home config can fail or appear logged out/misconfigured when called from the Codex app-server runtime.

Proposed fix

Add an explicit trusted-local override for the Codex app-server process HOME, while preserving the isolated CODEX_HOME.

A local prototype patch added support for:

plugins.entries.codex.config.appServer.homeDir

and an env fallback:

OPENCLAW_CODEX_APP_SERVER_HOME_DIR

The intended behavior is:

CODEX_HOME=<agentDir>/codex-home
HOME=<configured real user home> when this trusted override is set
default isolated HOME remains unchanged when unset

Validation from local prototype

A local source patch validated the approach with targeted Codex app-server config/auth tests, schema checks, and a live wrapper rollout across local Mac, MBP, and Windows gateways.

The live-compatible wrapper workaround is currently in use, but first-class config support would avoid requiring wrapper scripts per machine.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#authentication setup #request error #file not found #serialization error #model compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

openclaw - ✅(Solved) Fix Codex app-server isolated HOME breaks trusted local tool auth; add real-home override [2 pull requests, 1 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fix / Workaround

PR fix notes

PR #80315: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Description (problem / solution / changelog)

Summary

Changes

Real behavior proof

Changed files

PR #80318: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Description (problem / solution / changelog)

Summary

Changes

Real behavior proof

Changed files

Code Example

Summary

Observed behavior

Why this matters

Proposed fix

Validation from local prototype

Still need to ship something?

TRENDING

openclaw - ✅(Solved) Fix Codex app-server isolated HOME breaks trusted local tool auth; add real-home override [2 pull requests, 1 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fix / Workaround

PR fix notes

PR #80315: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Description (problem / solution / changelog)

Summary

Changes

Real behavior proof

Changed files

PR #80318: fix(codex): add homeDir override to use real OS HOME while keeping CODEX_HOME isolated

Description (problem / solution / changelog)

Summary

Changes

Real behavior proof

Changed files

Code Example

Summary

Observed behavior

Why this matters

Proposed fix

Validation from local prototype

Still need to ship something?

RELATED_DISCOVERY

TRENDING