openclaw/Peekaboo
openclaw/Peekaboo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
main
Peekaboo/docs/oauth.md
Peter Steinberger c8ab1e1821
fix(openai): use oauth for responses auth
2026-05-04 09:49:15 +01:00

3.2 KiB
Raw Permalink Blame History

summary read_when
How Peekaboo handles OAuth for OpenAI/Codex and Anthropic (Claude Pro/Max)
adding or debugging OAuth logins for OpenAI or Anthropic
explaining where tokens are stored and how they refresh

OAuth flows (OpenAI/Codex and Anthropic Max)

Peekaboo supports OAuth for two providers:

  • OpenAI/Codex via peekaboo config login openai
  • Anthropic Claude Pro/Max via peekaboo config login anthropic

These flows avoid storing API keys and instead keep refresh/access tokens in ~/.peekaboo/credentials (chmod 600).

Peekaboo shares the same credential layout as Tachikoma. Hosts can swap the profile directory (TachikomaConfiguration.profileDirectoryName) but never copy environment keys into the file; only explicit config add/config login writes.

What happens during login

  1. Generate PKCE values and open the provider’s authorize URL in the browser (also printed for headless use).
  2. You paste the returned code (and state when required) into the CLI.
  3. Peekaboo exchanges the code for refresh + access tokens and stores:
    • OPENAI_REFRESH_TOKEN, OPENAI_ACCESS_TOKEN, OPENAI_ACCESS_EXPIRES or
    • ANTHROPIC_REFRESH_TOKEN, ANTHROPIC_ACCESS_TOKEN, ANTHROPIC_ACCESS_EXPIRES
  4. No API key is written for OAuth flows.

How requests are sent

  • Providers resolve OAuth tokens and API keys through the shared Tachikoma credential manager. If the access token is expired, Peekaboo refreshes once per request and updates the credentials file.
  • Anthropic requests include the beta header used for Claude Max: anthropic-beta: oauth-2025-04-20,claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14.
  • If OAuth tokens are absent but an API key exists, the provider falls back to the API-key path.
  • OpenAI/Codex OAuth tokens may still be rejected by OpenAI API endpoints if the issued token lacks platform API scopes such as model or Responses access. In that case, use peekaboo config add openai <api-key> / OPENAI_API_KEY for see --analyze, image --analyze, and agent runs until the OAuth client is granted the required scopes.

Validating connectivity

  • peekaboo config show --timeout 30 pings each configured provider and reports status (ready (validated), stored (validation failed: <reason>), missing).
  • peekaboo config add <provider> <secret> validates immediately; failures are stored but warned.

Revoking access

  • OpenAI/Codex: revoke from your OpenAI account security page; then delete the stored tokens (peekaboo config edit or remove the keys from ~/.peekaboo/credentials).
  • Anthropic: revoke from your Claude account; remove the stored tokens the same way.

Headless / CI

  • If the browser cannot open, the CLI still prints the authorize URL; paste the resulting code back. Access/refresh storage and refresh logic are identical.

Troubleshooting

  • If validation fails after login, run peekaboo config show --timeout 10 --verbose to see the provider error.
  • OpenAI errors mentioning missing scopes are server-side OAuth scope failures, not local credential loading failures. Configure an API key for API-backed OpenAI features.
  • Stale access tokens are refreshed automatically; if refresh fails, rerun peekaboo config login <provider>.