PR #73943: fix(acpx): bridge Codex ACP auth

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/73943

Description (problem / solution / changelog)

Summary

• Problem: OpenClaw's Codex ACP wrapper forced an isolated Codex home that contained generated config only, so otherwise valid host Codex login state was not visible to Codex ACP sessions.
• Why it matters: #73910 reports managed Codex ACP failing even though direct ACPX with the user's normal Codex auth works.
• What changed: the isolated Codex home now bridges only an existing Codex auth.json; generated config.toml remains isolated, docs explain the behavior, and regression coverage locks in both the auth bridge and no-auth case.
• What did NOT change (scope boundary): Codex config hooks, ACP timeout handling, permission profiles, adapter commands, and OpenClaw runtime policy are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• 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 #73910
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the Codex ACP wrapper always set CODEX_HOME to OpenClaw's generated isolated home, but that home only received generated config and never saw the host Codex auth.json that direct Codex ACP runs used.
• Missing detection / guardrail: the existing regression test asserted config isolation but also asserted no source auth was bridged, so it locked in the broken managed-session behavior.
• Contributing context: the timeout rejection part of the issue was already fixed on main; this keeps that behavior unchanged.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/acpx/src/codex-auth-bridge.test.ts
• Scenario the test should lock in: source Codex auth.json is readable from the isolated Codex home, while source config.toml hooks are not imported and no OpenClaw ACP auth profile is synthesized.
• Why this is the smallest reliable guardrail: the bug is in wrapper/home preparation before the external adapter starts.
• Existing test that already covers this (if any): runtime.test.ts covers the unchanged Codex timeout ignore behavior.

User-visible / Behavior Changes

Codex ACP sessions can reuse existing host Codex login state when auth.json is present in the configured or default Codex home. The isolated Codex config.toml remains generated by OpenClaw.

Diagram (if applicable)

Before:
OpenClaw Codex ACP wrapper -> isolated codex-home with generated config only -> Codex ACP cannot see host auth

After:
OpenClaw Codex ACP wrapper -> isolated codex-home + bridged auth.json -> Codex ACP can use host login while config hooks stay isolated

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? Yes
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: the wrapper exposes the existing Codex auth.json to the same Codex ACP adapter process that would read it in a direct host Codex ACP run. The bridge is limited to auth.json; Codex config hooks/callbacks are not imported, OpenClaw ACP auth profiles are not synthesized, and permission/runtime controls are unchanged.

Repro + Verification

Environment

• OS: macOS local checkout
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: Codex ACP wrapper path
• Integration/channel (if any): ACPX bundled plugin
• Relevant config (redacted): test fixture CODEX_HOME with synthetic auth.json

Steps

1. Prepare a source Codex home with auth.json and a config.toml callback hook.
2. Run prepareAcpxCodexAuthConfig.
3. Inspect the generated isolated Codex home and wrapper.

Expected

• The isolated Codex home can read auth.json.
• Source config.toml hooks are not imported.
• The generated wrapper does not bake in the source Codex home path.

Actual

• Matches expected in the updated regression test.

Evidence

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

Human Verification (required)

• Verified scenarios: focused ACPX auth bridge test, no-source-auth side effect, unchanged Codex timeout ignore behavior, and the Codex plugin test that was blocking the changed gate.
• Edge cases checked: missing source auth leaves no generated auth, and source config hooks are not copied into the isolated home.
• What you did not verify: live Codex ACP login against a real user account.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: exposing host Codex auth to the managed Codex ACP adapter could be broader than the previous generated-home isolation.
  • Mitigation: the adapter already consumes the same auth in direct Codex ACP runs; OpenClaw bridges only auth.json, keeps config hooks isolated, and leaves ACP permissions/runtime policy unchanged.

Tests run

• git diff --check origin/main...HEAD
• pnpm test extensions/acpx/src/codex-auth-bridge.test.ts extensions/acpx/src/runtime.test.ts extensions/codex/index.test.ts -- -t "bridges source Codex auth without importing config hooks|installs an isolated Codex ACP wrapper without synthesizing auth|ignores unsupported Codex ACP timeout config controls|registers with capture APIs that do not expose conversation binding hooks yet"
• pnpm check:changed

Out of scope follow-ups

• Live Codex ACP smoke with a real account.
• Broader ACPX auth setup UX beyond the Codex auth.json bridge.
• Any change to ACP timeout controls or Codex permission/runtime policy.

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/tools/acp-agents.md (modified, +1/-1)
• extensions/acpx/src/codex-auth-bridge.test.ts (modified, +54/-1)
• extensions/acpx/src/codex-auth-bridge.ts (modified, +46/-1)
• extensions/codex/index.test.ts (modified, +6/-6)