mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(doctor): detect root openai_base_url Codex routing and agent-configured proxy ports (#4490)
## Description `headroom doctor` gives two false negatives on machines where the proxy is healthy (reported by a Headroom Desktop user on Windows 11; reproduced on macOS): 1. **Codex "not routed" when Codex routes through a root `openai_base_url`.** `check_codex_routing` only reads `[model_providers.<active>].base_url`. Codex also routes its built-in `openai` provider (the default when `model_provider` is unset) through a root `openai_base_url`. Headroom Desktop writes that layout, because the ChatGPT desktop app hides Dots, dictation and voice for any other `model_provider` (`openai/codex#55783`). Doctor now reads the root key for the `openai` provider and for configs with no `model_provider`, where it wins over a leftover `[model_providers.headroom]` table. Both keys only count at the TOML root (before the first table header): a `model_provider` under `[profiles.*]` applies only when that profile is selected, so it no longer hides the default session's route. 2. **A bare `headroom doctor` can't find a proxy on a port only the agents know about.** Without `--port`, discovery probes 8787, `HEADROOM_PORT`, deployment manifests and the wrap marker. Headroom Desktop (port 6767) and `wrap --port N` leave none of these, so the proxy row read "not reachable at 8787" with no hint. Discovery now also probes the loopback ports in Claude Code's `ANTHROPIC_BASE_URL` and Codex's active base URL, read from the same project and user configs as the routing rows (`.claude/settings.local.json`, `.claude/settings.json`, `.codex/config.toml`, then the user files), through the existing `extra=` hook of `find_live_proxy_elsewhere`. It still never adopts a port silently: the proxy row names the live port, as it already does for manifest ports. `codex_active_base_url` is shared with `init`'s port-alignment warning, which now sees the same routing. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/cli/doctor.py`: `codex_active_base_url` reads `model_provider` and `openai_base_url` from the TOML root only; with no root `model_provider` (or `"openai"`), a root `openai_base_url` wins, else the active provider table, else the legacy `[model_providers.headroom]` table. - `headroom/cli/doctor.py`: new `_configured_client_ports(claude_paths, codex_paths)` feeds the project and user Claude/Codex loopback ports to `find_live_proxy_elsewhere(extra=...)`. - `tests/test_cli_doctor.py`: root `openai_base_url` passes (with and without `model_provider`), beats an inactive `[model_providers.headroom]` table, is not hidden by a `[profiles.work] model_provider`; an `openai_base_url` inside a table is not root; a bare `doctor` names a live proxy on the port a user config, a project `.codex/config.toml` or a project `.claude/settings.local.json` routes to. - `tests/test_cli/test_port_alignment.py`: `init`'s alignment warning reads the root `openai_base_url` over an inactive `[model_providers.headroom]` table. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py -q 167 passed in 0.99s $ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_init_cli.py tests/test_cli/test_port_alignment.py tests/test_cli/test_wrap_stale_marker.py tests/test_corporate_tls.py tests/test_install/test_codex_install.py tests/test_offline_egress_chokepoint.py -q 477 passed, 2 skipped in 81.50s $ uvx ruff@0.17.0 check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py All checks passed! $ uvx ruff@0.17.0 format --check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py 3 files already formatted $ uv run --frozen --extra dev mypy headroom/cli/doctor.py Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: macOS, Headroom Desktop proxy (wheel 0.41.0) live on 127.0.0.1:6767, `~/.codex/config.toml` with root `model_provider = "openai"` + `openai_base_url = "http://127.0.0.1:6767/v1"`, Claude `ANTHROPIC_BASE_URL=http://127.0.0.1:6767` in `~/.claude/settings.json`. - Exact command / steps: `headroom doctor --json` and `headroom doctor --port 6767 --json`, once with the installed 0.41.0 wheel and once from this branch (`uv run --frozen headroom doctor`). - Observed result: The branch reports Codex as routed and names the live 6767 proxy, where 0.41.0 reported Codex as not routed and gave no hint. ```text 0.41.0, no --port: proxy fail not reachable at http://127.0.0.1:8787 codex warn not routed (no active provider base_url in config.toml) 0.41.0, --port 6767: codex warn not routed (no active provider base_url in config.toml) branch, no --port: proxy fail not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767 codex warn routed to port 6767, but doctor probed port 8787 (~/.codex/config.toml) branch, --port 6767: proxy pass running at http://127.0.0.1:6767 claude pass routed via ~/.claude/settings.json codex pass routed via ~/.codex/config.toml ``` Review follow-up (fd5e6fd5): a real `headroom doctor --json` process from85d32990and fromfd5e6fd5, each in a clean `HOME` (`env -i HOME=<tmp> PATH=/usr/bin:/bin`, so no `ANTHROPIC_BASE_URL` from the shell), against the same live 6767 proxy: ```text A root openai_base_url 6767 + [model_providers.headroom] 8787, no model_provider, --port 676785d32990codex warn routed to port 8787, but doctor probed port 6767fd5e6fd5codex pass routed via <home>/.codex/config.toml B root openai_base_url 6767 + [profiles.work] model_provider = "azure", --port 676785d32990codex warn not routed (no active provider base_url in config.toml)fd5e6fd5codex pass routed via <home>/.codex/config.toml C only <project>/.codex/config.toml (root openai_base_url 6767), no --port85d32990proxy fail not reachable at http://127.0.0.1:8787fd5e6fd5proxy fail not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767 ``` Live, for the built-in provider's credentials: Codex CLI 0.164.0 signed in with ChatGPT (`auth_mode = chatgpt`, no API key), config root `model_provider = "openai"` + `openai_base_url = "http://127.0.0.1:6767/v1"`, `codex exec --skip-git-repo-check -s read-only "Reply with exactly the word OK and nothing else."` answered `OK` (16,982 tokens). A routed request without credentials would have been rejected upstream. - Not tested: Windows, the reporter's platform (the change is platform-independent TOML and URL parsing). ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Stable. - Stable/default behavior changed: Yes, diagnostics only: `doctor` reports Codex as routed for root `openai_base_url` configs and probes the agents' configured loopback ports; the proxy is untouched. - Kill switch / disable path: `HEADROOM_PORT_DISCOVERY=0` disables the extra probing; the Codex detection has none, as it only changes a read-only report. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this commit. ## 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 - [ ] 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` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) Not applicable (CLI output above). ## Additional Notes Documentation: no doc describes the doctor's Codex detection or discovery candidates, so nothing to update. Related: #842 (Codex Desktop doctor support) and #3855 (doctor/live-port alignment). 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4490" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
JD Davis
parent
cd5e2b9e73
commit
222f2d1df3
+41
-5
@@ -46,7 +46,7 @@ from headroom.providers.claude import (
|
||||
)
|
||||
|
||||
from .main import get_version, main
|
||||
from .port_discovery import find_live_proxy_elsewhere, is_headroom_livez
|
||||
from .port_discovery import find_live_proxy_elsewhere, is_headroom_livez, loopback_port
|
||||
from .wrap import _read_wrap_marker, _wrap_marker_is_stale
|
||||
|
||||
PASS = "pass"
|
||||
@@ -59,6 +59,7 @@ DEFAULT_PROXY_PORT = 8787
|
||||
_LOOPBACK_URL_RE = re.compile(r"https?://(?:127\.0\.0\.1|localhost):(\d+)")
|
||||
_CODEX_BASE_URL_RE = re.compile(r'(?m)^[ \t]*base_url\s*=\s*"([^"\r\n]+)"')
|
||||
_CODEX_MODEL_PROVIDER_RE = re.compile(r'(?m)^[ \t]*model_provider\s*=\s*"([^"\r\n]+)"')
|
||||
_CODEX_OPENAI_BASE_URL_RE = re.compile(r'(?m)^[ \t]*openai_base_url\s*=\s*"([^"\r\n]+)"')
|
||||
|
||||
# Ollama's fixed default port. `ollama launch claude` writes
|
||||
# ``ANTHROPIC_BASE_URL=http://127.0.0.1:11434`` into the launched Claude Code
|
||||
@@ -573,7 +574,19 @@ def check_wrap_marker_staleness(settings_path: Path) -> CheckResult:
|
||||
|
||||
def codex_active_base_url(text: str) -> tuple[str, str | None]:
|
||||
"""Return ``(provider_id, base_url)`` for the active Codex provider in ``text``."""
|
||||
active_match = _CODEX_MODEL_PROVIDER_RE.search(text)
|
||||
first_table = re.search(r"(?m)^[ \t]*\[", text)
|
||||
root = text[: first_table.start()] if first_table is not None else text
|
||||
# Only a root `model_provider` picks the default session's provider; one
|
||||
# under `[profiles.*]` applies only when that profile is selected.
|
||||
active_match = _CODEX_MODEL_PROVIDER_RE.search(root)
|
||||
if active_match is None or active_match.group(1) == "openai":
|
||||
# A root `openai_base_url` re-points Codex's built-in `openai` provider
|
||||
# (the default when `model_provider` is unset), so it beats an inactive
|
||||
# `[model_providers.headroom]` table. Headroom Desktop routes this way
|
||||
# because the ChatGPT app hides features for any other provider.
|
||||
root_url = _CODEX_OPENAI_BASE_URL_RE.search(root)
|
||||
if root_url is not None:
|
||||
return "openai", root_url.group(1)
|
||||
provider_id = active_match.group(1) if active_match else "headroom"
|
||||
return provider_id, _codex_provider_base_url(text, provider_id)
|
||||
|
||||
@@ -661,6 +674,24 @@ def _codex_provider_base_url(text: str, provider_id: str) -> str | None:
|
||||
return base_url_match.group(1) if base_url_match else None
|
||||
|
||||
|
||||
def _configured_client_ports(
|
||||
claude_paths: Sequence[Path], codex_paths: Sequence[Path]
|
||||
) -> list[int]:
|
||||
"""Loopback ports the Claude Code and Codex configs (project and user) send traffic to.
|
||||
|
||||
Headroom Desktop (port 6767) and ``wrap --port N`` leave no deployment
|
||||
manifest, so without these a bare ``doctor`` only ever finds 8787.
|
||||
"""
|
||||
urls = [_claude_base_url_in(path)[0] for path in claude_paths]
|
||||
for path in codex_paths:
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8", errors="replace")
|
||||
except OSError:
|
||||
continue
|
||||
urls.append(codex_active_base_url(text)[1] or "")
|
||||
return [port for port in map(loopback_port, urls) if port is not None]
|
||||
|
||||
|
||||
def _codex_block_missing_openai_auth(
|
||||
text: str, config_path: Path, provider_id: str = "headroom"
|
||||
) -> bool:
|
||||
@@ -1211,20 +1242,25 @@ def doctor(
|
||||
health = probe_json(f"{base_url}/health", timeout=5.0) if livez else None
|
||||
stats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else None
|
||||
installed = get_version()
|
||||
project_claude_settings = Path.cwd() / ".claude" / "settings.json"
|
||||
project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"
|
||||
live_elsewhere = None
|
||||
if livez is None:
|
||||
# Cheap, bounded: only ports Headroom recorded (HEADROOM_PORT, 8787,
|
||||
# deployment manifests, the project's wrap marker), probed in parallel.
|
||||
# deployment manifests, the project's wrap marker) and the ports the
|
||||
# agents are configured for, probed in parallel.
|
||||
live_elsewhere = find_live_proxy_elsewhere(
|
||||
port,
|
||||
manifests=manifests,
|
||||
extra=_configured_client_ports(
|
||||
[project_local_claude_settings, project_claude_settings, claude_settings_path()],
|
||||
[codex_project_config_path(), codex_config_path()],
|
||||
),
|
||||
probe=lambda p: is_headroom_livez(
|
||||
probe_json(f"http://127.0.0.1:{p}/livez", timeout=0.5)
|
||||
),
|
||||
)
|
||||
|
||||
project_claude_settings = Path.cwd() / ".claude" / "settings.json"
|
||||
project_local_claude_settings = Path.cwd() / ".claude" / "settings.local.json"
|
||||
checks = [
|
||||
note_live_proxy_elsewhere(check_proxy_liveness(livez, base_url), live_elsewhere),
|
||||
check_proxy_readiness(livez, readyz, base_url),
|
||||
|
||||
@@ -434,6 +434,21 @@ class TestHookAlignment:
|
||||
message = init_mod.alignment_warning("codex", "init-user", probe=lambda p: False)
|
||||
assert message is not None and "--port 8787 codex" in message
|
||||
|
||||
def test_codex_root_openai_base_url_beats_an_inactive_headroom_table(
|
||||
self, home: Path, tmp_path: Path, monkeypatch
|
||||
) -> None:
|
||||
custom = tmp_path / "custom-codex"
|
||||
custom.mkdir()
|
||||
(custom / "config.toml").write_text(
|
||||
'openai_base_url = "http://127.0.0.1:9200/v1"\n[model_providers.headroom]\n'
|
||||
'base_url = "http://127.0.0.1:8787/v1"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
monkeypatch.setenv("CODEX_HOME", str(custom))
|
||||
monkeypatch.setattr(init_mod, "load_manifest", lambda profile: _manifest(profile, 8787))
|
||||
message = init_mod.alignment_warning("codex", "init-user", probe=lambda p: False)
|
||||
assert message is not None and "127.0.0.1:9200" in message
|
||||
|
||||
def test_session_start_emits_hook_json(self, claude_settings: Path) -> None:
|
||||
self._route_claude(claude_settings, 9200)
|
||||
result = CliRunner().invoke(
|
||||
|
||||
@@ -587,6 +587,57 @@ class TestCodexRouting:
|
||||
assert result.status == WARN
|
||||
assert "9999" in result.summary
|
||||
|
||||
def test_root_openai_base_url_on_builtin_provider_passes(self, tmp_path):
|
||||
"""Headroom Desktop's layout: built-in `openai` provider, root base URL."""
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text(
|
||||
'model_provider = "openai"\n'
|
||||
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
|
||||
'[projects."/work/app"]\n'
|
||||
'trust_level = "trusted"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
result = check_codex_routing(path, 6767)
|
||||
assert result.status == PASS, result.summary
|
||||
assert check_codex_routing(path, 8787).status == WARN
|
||||
|
||||
def test_root_openai_base_url_without_model_provider_passes(self, tmp_path):
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text('openai_base_url = "http://127.0.0.1:8787/v1"\n', encoding="utf-8")
|
||||
assert check_codex_routing(path, 8787).status == PASS
|
||||
|
||||
def test_openai_base_url_inside_a_table_is_not_root(self, tmp_path):
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text(
|
||||
'model_provider = "openai"\n'
|
||||
"[profiles.fast]\n"
|
||||
'openai_base_url = "http://127.0.0.1:8787/v1"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_codex_routing(path, 8787).status == WARN
|
||||
|
||||
def test_root_openai_base_url_beats_an_inactive_headroom_table(self, tmp_path):
|
||||
"""No root `model_provider`: Codex uses its built-in `openai`, not the table."""
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text(
|
||||
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
|
||||
"[model_providers.headroom]\n"
|
||||
'base_url = "http://127.0.0.1:8787/v1"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_codex_routing(path, 6767).status == PASS
|
||||
assert check_codex_routing(path, 8787).status == WARN
|
||||
|
||||
def test_profile_model_provider_does_not_hide_the_default_route(self, tmp_path):
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text(
|
||||
'openai_base_url = "http://127.0.0.1:6767/v1"\n'
|
||||
"[profiles.work]\n"
|
||||
'model_provider = "azure"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_codex_routing(path, 6767).status == PASS
|
||||
|
||||
def test_no_marker_warns(self, tmp_path):
|
||||
path = tmp_path / "config.toml"
|
||||
path.write_text('model = "gpt-5"\n', encoding="utf-8")
|
||||
@@ -986,6 +1037,49 @@ class TestDoctorCommand:
|
||||
assert "http://127.0.0.1:8789/livez" in seen
|
||||
assert not any("127.0.0.1:8787" in url for url in seen)
|
||||
|
||||
def test_names_the_live_port_the_agents_are_configured_for(self, runner, isolated, monkeypatch):
|
||||
"""Headroom Desktop runs on 6767 and records no deployment manifest."""
|
||||
monkeypatch.setenv("HEADROOM_PORT_DISCOVERY", "1")
|
||||
(isolated / "settings.json").write_text(
|
||||
json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"}}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
def desktop_probe(url, timeout=2.0):
|
||||
return LIVEZ_OK if url == "http://127.0.0.1:6767/livez" else None
|
||||
|
||||
monkeypatch.setattr(doctor_mod, "probe_json", desktop_probe)
|
||||
result = runner.invoke(main, ["doctor", "--json"])
|
||||
proxy = next(c for c in json.loads(result.output)["checks"] if c["name"] == "proxy")
|
||||
assert "a Headroom proxy IS running on port 6767" in proxy["summary"]
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("relative", "content"),
|
||||
[
|
||||
("project-codex.toml", 'openai_base_url = "http://127.0.0.1:6767/v1"\n'),
|
||||
(
|
||||
".claude/settings.local.json",
|
||||
json.dumps({"env": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:6767"}}),
|
||||
),
|
||||
],
|
||||
)
|
||||
def test_names_the_live_port_only_a_project_config_routes_to(
|
||||
self, runner, isolated, monkeypatch, relative, content
|
||||
):
|
||||
monkeypatch.setenv("HEADROOM_PORT_DISCOVERY", "1")
|
||||
monkeypatch.chdir(isolated)
|
||||
path = isolated / relative
|
||||
path.parent.mkdir(exist_ok=True)
|
||||
path.write_text(content, encoding="utf-8")
|
||||
|
||||
def desktop_probe(url, timeout=2.0):
|
||||
return LIVEZ_OK if url == "http://127.0.0.1:6767/livez" else None
|
||||
|
||||
monkeypatch.setattr(doctor_mod, "probe_json", desktop_probe)
|
||||
result = runner.invoke(main, ["doctor", "--json"])
|
||||
proxy = next(c for c in json.loads(result.output)["checks"] if c["name"] == "proxy")
|
||||
assert "a Headroom proxy IS running on port 6767" in proxy["summary"]
|
||||
|
||||
|
||||
class TestCostTrackerBudgetKeys:
|
||||
def test_stats_exposes_budget_config(self):
|
||||
|
||||
Reference in New Issue
Block a user