Provider & Auth Strategy

Open Agent SDK is API-aligned with Claude Agent SDK workflows, but intentionally supports a broader provider strategy.

Use this guide to decide how to configure providers without locking your architecture too early.

Provider selection model

Pick one default provider per environment, then keep at least one fallback provider for operational resilience.

Primary provider: best fit for your latency, cost, and model quality targets
Fallback provider: used for outages, quota limits, or targeted workloads
Migration provider: temporary provider during staged migrations

Recommended pattern:

Store provider keys in environment variables
Resolve credentials at runtime by environment
Keep provider selection explicit in integration code
For Codex OAuth, reuse a local codex login session instead of hardcoding API keys

Typical variables:

Codex is a separate provider path in the SDK:

const result = await prompt('Summarize this repo.', {
  model: 'gpt-5.4',
  provider: 'codex',
});

Recommended setup:

Run codex login
Let the SDK import ~/.codex/auth.json
Only override codexOAuth.codexAuthPath or OAS_CODEX_AUTH_PATH when you need a non-default login location

For non-interactive runners such as terminal-bench, you can also:

Prefer OAS_CODEX_OAUTH_JSON or OAS_CODEX_AUTH_PATH when you want automatic refresh behavior.

Use provider: 'openai' with OPENAI_API_KEY when you want standard usage-based OpenAI Platform billing instead of Codex OAuth.

Use baseURL only when you need:

Keep default base URLs in local development unless you have a hard requirement to override.