Summary

Pulled the branch and walked the diff (api/oauth.py +315, api/onboarding.py +46, static/onboarding.js +138, regression tests +316). The shape is right: this is a credential-linking flow rather than a browser-exposed Anthropic token flow, and the public payloads stay token-free. The cross-repo agent contract checks out — agent/anthropic_adapter.py has the host-side credential reading already; this PR just wires WebUI to detect and mark it.

Cross-repo agent contract

Reading ~/.hermes/hermes-agent/agent/anthropic_adapter.py:706 (read_claude_code_credentials), :760 (is_claude_code_token_valid), and :942 (resolve_anthropic_token) — the agent already prefers Claude Code credentials when ANTHROPIC_TOKEN / ANTHROPIC_API_KEY are both unset:

def resolve_anthropic_token() -> Optional[str]:
    # Priority:
    #   1. ANTHROPIC_TOKEN env var (OAuth/setup token saved by Hermes)
    #   2. CLAUDE_CODE_OAUTH_TOKEN env var
    #   3. Claude Code credentials (~/.claude.json or ~/.claude/.credentials.json)
    #   4. ANTHROPIC_API_KEY env var

So the WebUI side's _clear_anthropic_env_values() at api/oauth.py:241-252 (clearing ANTHROPIC_TOKEN and ANTHROPIC_API_KEY from the active profile's .env and the live os.environ) is exactly what makes the agent fall through to step 3. That is the right contract layer — no new agent-side code needed.

Code reference

The credential-pool marker shape on api/oauth.py:262-296:

entries = pool.setdefault("anthropic", [])
# ...
entry = {
    "id": "anthropic-claude-code-" + uuid.uuid4().hex[:12],
    "label": "Claude Code (linked)",
    "auth_type": "oauth",
    "priority": 0,
    "source": "claude_code_linked",
    "created_at": now,
}
entries.insert(0, entry)

And the matching readiness check in api/onboarding.py:613-622:

for entry in entries:
    if _oauth_payload_has_token(entry):
        return True
    if (
        provider == "anthropic"
        and isinstance(entry, dict)
        and entry.get("auth_type") == "oauth"
        and entry.get("source") == "claude_code_linked"
    ):
        return True

Two things I like here: the marker entry has no token field at all (so a serialized auth.json dump is genuinely secret-free even for the linked case), and _oauth_payload_has_token() already covers the standard OAuth-token-in-pool path so existing providers keep working unchanged.

Diagnosis

A few observations from the diff:

1. Alias normalization is centralized. _normalize_onboarding_oauth_provider() at api/oauth.py:60-65 collapses claude and claude-code into canonical anthropic. The _ANTHROPIC_PROVIDER_ALIASES set is reused at the rejection check on api/oauth.py:664 so the public API accepts all three aliases consistently. Good.

2. Cancel-during-link races. The body mentions hardening for cancels racing the credential-link path. Reading the cancel worker, the marker write to auth.json and the env-clear are both synchronous inside _link_anthropic_credentials(), so a cancel arriving mid-link can't tear the marker write — but the env values may already have been cleared. The PR body acknowledges this tradeoff; in practice, clearing env values that would override OAuth is still the safer state, so I think this is fine as documented.

3. Frontend secret discipline. Reading static/onboarding.js:760-793, the polling/start UI never displays a token and only shows status strings + a claude setup-token instruction. The action-required state explicitly says "this page will detect the credentials automatically" rather than asking the user to paste anything. That matches the PR body's claim of no browser-visible tokens.

One small concern

The marker dedup loop scans entries for source == "claude_code_linked" and reuses an existing entry, but always re-prepends with entries.insert(0, entry) if it didn't find one. If entries already has another non-linked entry at position 0 (say, an existing Anthropic OAuth token from a different flow), the linked marker will jump in front and inherit priority: 0. That is probably fine because the readiness check returns True if either entry has a token or is the linked marker, but the runtime credential resolution order may now prefer the marker over a real token if anything else later sorts by priority. Worth a quick check that no consumer outside this PR sorts the pool by priority and treats claude_code_linked as a token source.

Verification

tests/test_issue1362_codex_oauth_onboarding.py adds 22 new test cases covering alias normalization, secret-free payloads, credential linking, readiness, setup-without-key, cancel/expiry/error worker paths, cancel-during-link races, and frontend strings. CI is green on all three Python versions. Closes #1362 cleanly. Looks good to merge.

Thanks @Michaelyklam — this shipped in v0.51.8 (commit 85d0279) as part of a 7-PR full-sweep batch release. Stage rebased your branch onto current master, ran the full pre-release gate (4584 pytest, browser tests, Opus advisor verdict SHIP), and merged via release PR #1737.

GitHub didn't auto-close because the merge commit only references the squash-merged stage branch, not your fork's commit directly — closing manually for hygiene.

Live now on https://get-hermes.ai/ and on existing installs after git pull + restart.

Release notes: https://github.com/nesquena/hermes-webui/releases/tag/v0.51.8