mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(codex): explain why wrapped Codex runs without the shared server (#3899)
## Description `headroom wrap codex` passes proxy routing as a `--config` override (`openai_base_url=…`, or `model_providers.<id>.base_url=…` for custom providers). This keeps routing scoped to the launched process and leaves `~/.codex/config.toml` untouched, by design (#1507, #2160). Codex 0.159 runs any session that has command-line overrides in embedded mode, so wrapped sessions always print `Running without the shared background server` and never use Codex's shared background server. Env-only routing can't replace the override. ChatGPT-subscription Codex ignores `OPENAI_BASE_URL` (see5c7a5b48/d54c5b6a), so `openai_base_url` has to come from config. A shared server also serves every session at once, so a per-session base URL can't apply to it. The issue accepts "explicit documentation of the limitation", so this PR does that: - `wrap codex` now prints a one-line note at launch that explains embedded mode and points to the persistent alternative. - The proxy docs describe the limitation and the alternative: `headroom init codex` (project) or `headroom init -g codex` (user) writes the routing to Codex's own config, so a plain `codex` launch keeps the shared server. Closes #3888 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/cli/wrap.py`: new `_CODEX_EMBEDDED_MODE_NOTE`. `_codex_session_launch_settings` appends it to the launch display lines, so it prints under `Launching CODEX…` for both the built-in `openai` provider and custom providers. - `docs/content/docs/proxy.mdx`: new paragraph under "Agent wrapping" covering why wrapped Codex uses embedded mode, plus the `headroom init codex` / `headroom init -g codex` alternative and its persistent scope. - `tests/test_cli/test_wrap_codex.py`: asserts the note for both provider paths. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`): not run successfully. My local mypy stops on an unrelated numpy stub syntax error in this env - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ pytest tests/test_cli/test_wrap_codex.py -q 101 passed in 5.68s $ pytest tests/test_cli -q -k codex 176 passed, 738 deselected in 6.84s $ ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py All checks passed! ``` ## Real Behavior Proof - Environment: macOS, Python 3.12, branch head - Exact command / steps: `python -c "import headroom.cli.wrap as w; print(w._CODEX_EMBEDDED_MODE_NOTE)"` - Observed result: the note prints as expected (below), and the codex wrap tests assert it appears in the launch display for both the built-in `openai` provider and custom providers: ```text Note: session-scoped routing runs Codex without its shared background server (embedded mode). To keep the shared server, route through Codex config instead: run `headroom init codex` (or `headroom init -g codex`) once, then start `codex` directly. ``` - Not tested: a live `headroom wrap codex` launch against Codex CLI 0.159.2 (Codex isn't installed on my machine). I also didn't verify end to end that an `init`-configured plain `codex` launch keeps the shared server, though that path passes no command-line overrides. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: N/A - Stable/default behavior changed: No. Routing is unchanged; only one extra banner line is printed. - Kill switch / disable path: N/A - Unsafe override required: No - Qualification impact: None - Rollback path: revert this PR ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes A follow-up could skip the `--config` override when Codex's effective config already routes the selected provider to this proxy, for example after `headroom init codex`. That would let `wrap codex` itself keep the shared server. The trade-off is losing the per-project `/p/<project>` URL prefix for those sessions, so I left it out of this PR. Happy to add it if maintainers want that behavior.
This commit is contained in:
@@ -803,6 +803,22 @@ headroom wrap cursor
|
||||
headroom wrap grok-build
|
||||
```
|
||||
|
||||
`headroom wrap codex` keeps routing scoped to the Codex process it launches: it
|
||||
passes the proxy URL as a `--config` override and never writes it to
|
||||
`~/.codex/config.toml`. Codex runs any session started with command-line
|
||||
overrides in embedded mode, so a wrapped session does not use Codex's shared
|
||||
background server and Codex prints "Running without the shared background
|
||||
server". If you want the shared server, write the proxy routing to Codex's own
|
||||
config instead, then start `codex` directly:
|
||||
|
||||
```bash
|
||||
headroom init codex # this project's .codex/config.toml (trusted projects)
|
||||
headroom init -g codex # ~/.codex/config.toml, for every project
|
||||
```
|
||||
|
||||
That routing is persistent: it applies to every Codex session in that scope
|
||||
until you remove it.
|
||||
|
||||
Cursor reads model endpoints from its settings UI, so `headroom wrap cursor`
|
||||
does not rewrite Cursor configuration or launch the app. After it starts the
|
||||
proxy, copy the printed base URL into Cursor's model settings.
|
||||
|
||||
@@ -2915,6 +2915,13 @@ def _codex_dotted_key(*parts: str) -> str:
|
||||
)
|
||||
|
||||
|
||||
_CODEX_EMBEDDED_MODE_NOTE = (
|
||||
"Note: session-scoped routing runs Codex without its shared background server "
|
||||
"(embedded mode). To keep the shared server, route through Codex config instead: "
|
||||
"run `headroom init codex` (or `headroom init -g codex`) once, then start `codex` directly."
|
||||
)
|
||||
|
||||
|
||||
def _codex_session_launch_settings(
|
||||
*, port: int, codex_args: tuple[str, ...], environ: dict[str, str]
|
||||
) -> tuple[tuple[str, ...], dict[str, str], list[str]]:
|
||||
@@ -2974,6 +2981,11 @@ def _codex_session_launch_settings(
|
||||
|
||||
if project and "HEADROOM_PROJECT" not in env:
|
||||
env["HEADROOM_PROJECT"] = project
|
||||
# Routing is passed as ``--config`` so it stays scoped to this process, and
|
||||
# Codex runs any session with command-line overrides in embedded mode,
|
||||
# without its shared background server (#3888). Say so up front, and point
|
||||
# at the persistent alternative that leaves the shared server in play.
|
||||
display.append(_CODEX_EMBEDDED_MODE_NOTE)
|
||||
config_args = tuple(item for override in overrides for item in ("--config", override))
|
||||
return (*config_args, *codex_args), env, display
|
||||
|
||||
|
||||
@@ -1448,7 +1448,10 @@ def test_codex_session_launch_settings_keep_routing_process_local(
|
||||
)
|
||||
assert env["CODEX_HOME"] == str(codex_home)
|
||||
assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9898/v1"
|
||||
assert display == ["OPENAI_BASE_URL=http://127.0.0.1:9898/v1"]
|
||||
assert display == [
|
||||
"OPENAI_BASE_URL=http://127.0.0.1:9898/v1",
|
||||
wrap_mod._CODEX_EMBEDDED_MODE_NOTE,
|
||||
]
|
||||
assert config_file.read_text(encoding="utf-8") == original_config
|
||||
|
||||
|
||||
@@ -1467,7 +1470,7 @@ def test_codex_session_launch_settings_preserve_custom_provider_identity(
|
||||
)
|
||||
config_file.write_text(original_config, encoding="utf-8")
|
||||
|
||||
args, env, _ = wrap_mod._codex_session_launch_settings(
|
||||
args, env, display = wrap_mod._codex_session_launch_settings(
|
||||
port=9898,
|
||||
codex_args=("--profile", "work"),
|
||||
environ={"CODEX_HOME": str(codex_home)},
|
||||
@@ -1482,6 +1485,8 @@ def test_codex_session_launch_settings_preserve_custom_provider_identity(
|
||||
'="HEADROOM_CODEX_UPSTREAM_BASE_URL"'
|
||||
) in args
|
||||
assert env[wrap_mod._UPSTREAM_BASE_URL_ENV_VAR] == "https://api.example.test/v1"
|
||||
# Custom-provider routing also goes through --config, so the note applies (#3888).
|
||||
assert display[-1] == wrap_mod._CODEX_EMBEDDED_MODE_NOTE
|
||||
assert config_file.read_text(encoding="utf-8") == original_config
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user