feat(providers): support Claude subscription (OAuth) auth; docs omit API key requirement

[cboettig]

Problem Statement

The documentation and CLI examples present Claude as the first-class, default provider throughout — it is the canonical example in the README, provider docs, and getting-started guides. However, there is a silent incompatibility that affects the majority of Claude users: Claude Max/Pro subscription accounts authenticate via OAuth, not an API key, and OpenShell's claude provider type currently requires ANTHROPIC_API_KEY.

This causes a silent failure: openshell provider create --name claude --type claude --credential ANTHROPIC_API_KEY=<oauth-token> succeeds with ✓ Created provider but shows Credential keys: <none> — no error, no hint that subscription auth is unsupported.

The documentation never mentions this limitation, leaving subscription users with no path forward and no explanation.

Agent Diagnostic

My agent investigated this using the CLI directly:

$ openshell provider create --name claude --type claude --from-existing
Error: × no existing local credentials/config found for provider type 'claude'

$ openshell provider create --name claude --type claude --credential ANTHROPIC_API_KEY=<oauth-token>
✓ Created provider claude

$ openshell provider get claude
Credential keys: <none>
Config keys:     <none>

The OAuth access token (sk-ant-oat01-...) stored by Claude Code in ~/.claude/.credentials.json is not recognized. The --from-existing path does not discover it. No skill or diagnostic resolves this — the auth path simply does not exist for subscription users.

Proposed Design

Two complementary fixes:

1. Documentation fix (immediate): Add a note wherever Claude is shown as an example that ANTHROPIC_API_KEY requires an Anthropic API account (console.anthropic.com), which is separate from Claude.ai subscriptions. This is a one-line callout that prevents the silent dead-end.

2. Headless OAuth flow (longer term): Claude Code already supports a headless authentication routine — launch without credentials and authenticate via URL → OTP. OpenShell could support this for the claude provider type: if no API key is configured, the sandbox launch triggers the headless flow (print URL, prompt for OTP), storing the resulting OAuth token for the session. This is analogous to how claude CLI handles --headless auth and would make the subscription path fully first-class.

The credential storage infrastructure already handles opaque token values (demonstrated by --config KEY=VALUE working correctly). The missing piece is the OAuth initiation flow and token refresh.

Alternatives Considered

• Use OpenAI provider instead: Works today but doesn't address the Claude case.
• Require API key only: Current behavior, but misaligned with docs that imply Claude "just works."
• Surface the limitation as an error: Minimum fix — at least fail loudly rather than silently creating an empty provider.

Checklist

• Reviewed existing issues and architecture docs
• This is a design proposal, not a "please build this" request

[ben-cobb]

Encountered the same issue with my Claude subscription. As a temporary workaround I’ve been authenticating directly inside a sandbox created via:

openshell sandbox create --from base

(or --from ollama). In my experience, the auth persists across disconnect/reconnect cycles, so I've only needed to do it once per sandbox.