OpenAI with DevFlow: setup, scope and limits

An OpenAI key lets DevFlow's OpenCode agents run GPT and o-series models on your own account. Every run whose model ID starts with openai/ uses it, and the three tiers decide which roles those are. Setup is 5 steps in Workspace Settings → Billing → Model access.

Kind

Model provider

Where to set it up

Workspace Settings → Billing → Model access

Plan

All plans

Agent roles

Any OpenCode role set to an openai/ model

Verified

1 Oct 2026

Setup steps

1. Create an API key. On the OpenAI platform, create a key dedicated to DevFlow.
2. Open the Billing tab. As an owner, open the Billing tab and find "Model access"; click "Manage keys" when no provider cards are shown.
3. Add the key under Add provider. First-party cards stay hidden until a key exists. In "Add provider", enter OPENAI_API_KEY as the name, paste the secret into "API key" and click "Add".
4. Test the key. Click "Test" on the new card. DevFlow sends the key as a Bearer token to https://api.openai.com/v1/models and shows whether the request was accepted. A key typed into the field but not yet saved is tested in place of the stored one, so a replacement can be checked before it goes live.
5. Assign tiers. In the Execution tab, set the Fast, Pro or Max tier, or "OpenCode Model", to an ID with the openai/ prefix, for example openai/o3.

What it does

Each agent role draws from one of 3 tiers. Fast covers summaries, triage, chat, classification and scanning; Pro covers the implementer, fixer, verifier and preflight; Max covers planning, decomposition, diagnosis and the learner.

Pointing a tier at an ID such as openai/gpt-5 moves every role on that tier at once. A single role can still be pinned under Advanced execution, and a task can carry its own override, set in the task's Overview tab and editable while the task is idle, planning, in plan review or failed.

Resolution runs from the narrowest setting to the broadest: the task's override, then the workspace's per-role override, then the tier, then the workspace default. The first one that names a backend and a model wins, and roles left on "Inherit" simply use their tier.

OpenAI is one of the two providers, with Anthropic, that the optional context-compression proxy can front. The proxy is switched on per workspace in the Execution tab, and DevFlow checks that its URL is http or https only at the moment it is enabled.

Before the first task, "Check readiness" in the Repositories tab confirms that the default model and every per-role override have a credential, counting stored keys and the server environment alike. A role set to a provider without one shows up there instead of failing mid-task.

A single run may last up to 90 minutes and is stopped after 45 minutes without output, whatever the provider. Only the operator can change either limit, through AGENT_TIMEOUT_MINUTES and AGENT_IDLE_TIMEOUT_MINUTES.

IDs that start with ollama/ are rejected by the settings validators, so a locally served model cannot replace a hosted one on any tier.

Requirements

• The owner role in the DevFlow workspace to add, test, replace or remove the key.
• The exact env name; DevFlow upper-cases what you type and accepts letters, digits and underscores only.
• An account with API access to the GPT or o-series models that the tiers name.

Limits

• The server operator can also supply a key of that name through the server environment; a stored key always wins.
• With the model relay on, which container mode enforces, each run receives a short-lived token instead of the secret, and the relay swaps the stored key in.
• Rate-limit, overload and unavailable answers (429, 529 and 503) are retried with exponential backoff, from 2 to 60 seconds, for up to 4 attempts; other errors fail the run at once.

Sources

Every fact above comes from these files in the DevFlow repository.

• internal/relay/providers.go
• internal/agent/opencode_backend.go
• internal/agent/backend.go
• internal/agent/transient_error.go
• internal/api/opencode_key_tester.go
• internal/api/handlers_opencode_keys.go
• internal/api/server.go
• internal/api/handlers_readiness.go
• web/src/lib/components/ApiKeysManager.svelte
• web/src/lib/components/billing/ModelAccess.svelte
• web/src/lib/components/WorkspaceSettings.svelte
• CLAUDE.md
• internal/api/handlers_workspace.go