Jan-Marlon Leibl 34b2f7314e docs(claude-code): document oauthToken config and the macOS SDK bug ...

After investigating, the @anthropic-ai/claude-agent-sdk has a macOS-
specific upstream bug that breaks subscription auth: the SDK isolates
CLAUDE_CONFIG_DIR per invocation and tries to copy
~/.claude/.credentials.json, which doesn't exist on macOS (creds live
in the Keychain). The spawned CLI then misclassifies the OAuth token
as an API key and bills against API credits.

Changes:

- ClaudeCodeConfig.oauthToken: new optional config field that exports
  CLAUDE_CODE_OAUTH_TOKEN before invoking the SDK. Wired up and ready
  for when the upstream bug is fixed; currently affected by it on macOS.
- README, JSDoc: clearly document the limitation. API-key mode works
  reliably; subscription mode is broken on macOS pending upstream fix.
- billing_error message: explain the bug and recommend ClaudeProvider +
  ANTHROPIC_API_KEY as the workaround so users can self-diagnose.
- examples/claude-code.ts: read CLAUDE_CODE_OAUTH_TOKEN from env so the
  smoke test attempts the subscription path when configured.

No code changes silently in flight — when the SDK fixes the Keychain
handling, subscribers will Just Work without any code changes here.

2026-05-21 15:10:57 +02:00

2.1 KiB

Raw Blame History

View Raw