umbrella: OpenClaw/Codex auth support for GBrain providers

[100yenadmin]

TL;DR

GBrain should support host-provided credential sources for providers without making any one host a hard dependency. The active path should build on the current recipe/auth architecture and #698 rather than the stale resolver PR: core provider recipes stay provider-neutral; host adapters translate OpenClaw/Codex/Hermes/etc. auth state into an explicit credential source without leaking tokens into tool payloads, logs, or generated context.

flowchart LR
  Host["agent host\nOpenClaw / Codex / Hermes / Claude Code"] --> Auth["host-owned auth/profile/OAuth"]
  Auth --> Adapter["GBrain host adapter"]
  Adapter --> Resolver["credential-source resolver"]
  Resolver --> Recipe["Recipe.resolveAuth / provider recipe"]
  Recipe --> Provider["OpenAI / Voyage / Gemini / local provider"]

Loading

Why This Matters

Users often already authenticated inside their agent host. Requiring every GBrain install to also collect and store provider API keys creates friction, duplicate billing/config work, and a worse default for managed user fleets.

The product goal is not "hide API keys with another API-key wrapper." The goal is a clean boundary:

• host owns login/session/profile state
• GBrain core owns provider calls, capability detection, and readiness checks
• adapter/resolver passes only minimum credential-source metadata
• secrets never appear in model-visible payloads, CLI output, route responses, or logs

Concrete Examples

• OpenClaw can expose an OAuth-backed model runtime to a GBrain adapter without requiring the user to paste OPENAI_API_KEY into GBrain.
• Codex Desktop can launch local gbrain serve while the host plugin contributes credential-source metadata through a narrow adapter contract.
• Claude Code or Hermes can implement the same contract later without core GBrain importing host-specific SDKs.
• CI and headless servers can keep using plain env vars, with process env remaining the highest-precedence escape hatch.

Current State

• The old provider-auth resolver PR was closed as stale because upstream now has the v0.32 recipe/auth architecture.
• feat: add OpenAI Codex OAuth provider #698 is the active Codex OAuth provider direction and should inform this work.
• Recipe.resolveAuth is the right upstream seam to plug into; new work should not bypass it.

Acceptance Criteria

• Define a provider-neutral credential-source shape that recipes can consume.
• Integrate with Recipe.resolveAuth / existing provider recipes instead of creating a parallel auth path.
• Keep process env as the highest-priority override for regular CLI/server installs.
• Expose redacted readiness metadata for commands such as gbrain providers explain, list, or test.
• Include fake-token tests proving secrets are never printed, logged, serialized into route payloads, or included in agent-visible context.
• Include at least one host-adapter fixture proving the core seam works without importing a real host runtime.

Non-Goals

• Do not make OpenClaw, Codex Desktop, Hermes, or Claude Code required for GBrain.
• Do not print OAuth access tokens or refresh tokens.
• Do not claim subscription-backed embeddings unless the provider/runtime actually supports embeddings.
• Do not merge stale PR feat: provider auth resolver seam #642 as-is.

Agent Implementation Notes

Start from the current recipe/auth files on master. Build the smallest seam that lets a host adapter resolve credentials before the provider recipe creates its client. Keep host code outside core. Use fake credentials in tests and assert redaction at every public boundary.

[100yenadmin]

Update: opened #642 as the current master/v0.27 rebuild of the durable provider-auth resolver seam. It supersedes stale PRs #545 and #546 and keeps env credentials highest-priority while adding explicit OpenClaw/Codex profile auth as a secondary source.

[Rosevari]

+1 from a daily gbrain user on the Max subscription. Posting use case + signal demand for the Claude Code OAuth path specifically (separately from the OpenClaw/Codex paths #698 and #977 already in flight).

Use case

Running gbrain on a personal Mac Mini as the knowledge layer for a solo agency business. Stack:

• gbrain v0.35.0.0, PGLite engine, 1200+ pages, ~3 active Claude Code sessions/day
• signal-detector hook fires on every UserPromptSubmit → submits Haiku subagent jobs (~30-100/day)
• Dream cycle nightly
• All currently billing to ANTHROPIC_API_KEY separately from Max subscription

What I'd want

Once #621 (provider/helper-friendly subagent calls) lands and the Anthropic Agent SDK credit pool goes live on June 15:

# In ~/.gbrain/config.json or env
{
  "auth": {
    "provider": "claude-code-oauth",
    "fallback": "anthropic-api-key"
  }
}

Or simpler: prefer CLAUDE_CODE_OAUTH_TOKEN env var over ANTHROPIC_API_KEY when both are present, paired with a swap from @anthropic-ai/sdk to @anthropic-ai/claude-agent-sdk in the subagent call path (src/core/minions/handlers/subagent.ts based on file changes seen in #564).

Why this matters for the gbrain userbase

Plenty of solo operators / indie hackers using gbrain on Pro/Max already pay $20-200/mo for Claude Code. The new Agent SDK credit pool ($20 Pro / $100 Max5x / $200 Max20x per month, separate from the interactive cap) would cover most personal gbrain background-loop traffic at zero marginal cost.

For me specifically: ~$5-15/mo current Anthropic API spend would drop to $0 since it fits inside the $100 Max5x Agent SDK monthly credit allocation.

Relation to other open work

• Make dream synthesis and subagent LLM calls provider/helper-friendly #621 is the architectural prerequisite — needs to land first
• feat: add OpenAI Codex OAuth provider #698 / feat: support Codex OAuth for dream synthesis #977 are the parallel Codex / OpenAI OAuth paths
• Adding a Claude Code OAuth path completes the auth-provider matrix Garry's roadmap implies

Happy to test patches against my install (production-validated PGLite, full multi-source + autopilot + supervisor setup, recent v0.30.2 → v0.35.0.0 upgrade).

[100yenadmin]

@Rosevari thanks for the nudge; I'll add claude code oauth as well so it covers both Codex and Claude Code to my PR.