Agent harnesses: OpenCode, Claude Agent, and Codex
Compare the three agent harnesses, choose one when you create a session, and learn how Claude Agent and Codex sessions authenticate and run.
This page explains what an agent harness is, how OpenCode, Claude Agent, and Codex differ, and what to expect from Claude Agent and Codex sessions.
One harness per session
The agent harness is the coding agent that runs inside the sandbox. Every session runs on exactly one harness, chosen when the session is created and fixed for its lifetime, like the base branch.
- Child sessions inherit their parent's harness.
- An automation carries a harness for the sessions it creates.
- Sessions started by Linear run on the harness chosen in Settings › Integrations › Linear, globally or per repository (OpenCode by default). A model the chosen harness cannot run, such as one from a
model:gpt-*label on Claude Agent, is refused with an error activity and no coding session. Choose a compatiblemodel:*label, user preference, or default model, or change the integration harness, then delegate again. - Sessions started by Slack run on the harness the user chose in the Slack app's Home tab, else the one chosen in Settings › Integrations › Slack (OpenCode by default). A request whose model that harness cannot run, such as one from
!model openai/gpt-5.4or an App Home preference on Claude Agent, is refused rather than started on OpenCode. A Slack thread keeps its session's harness. - Sessions started by GitHub run on the harness chosen in Settings › Integrations › GitHub, globally or per repository (OpenCode by default). A model the chosen harness cannot run is refused with a reply on the PR and no session. Retry a mention with a compatible
!model, update the default model, or change the integration harness. - OpenCode is the default harness.
All three integrations preserve the selected harness rather than falling back to OpenCode. For GitHub and Linear, explicitly selecting a restricted harness such as Claude Agent or Codex requires a compatible default model at the same settings level (global or repository). Omitted repository harness and model fields inherit individually. Save validation checks each explicit level, not the merged global/repository pair; cross-level mismatches are refused at launch. See GitHub settings and Linear settings.
Existing GitHub and Linear settings that select Claude Agent without a default model are not automatically migrated. They remain readable, and rejected saves leave them unchanged. Before saving any edits, including unrelated settings, an administrator must open Settings > Integrations > GitHub or Linear and choose a compatible Anthropic default model at every global or repository level that explicitly selects Claude Agent. A global model alone does not repair an explicit repository harness override. Alternatively, switch that level to OpenCode, or remove the repository harness override to inherit global settings.
All three harnesses emit the same session events (tokens, tool calls, steps, warnings), so the session page, timeline, and diff work the same way on any of them.
Comparison
| OpenCode | Claude Agent | Codex | |
|---|---|---|---|
| Models | Every model in the catalog | Anthropic models only | OpenAI models that support Codex (see the OpenAI catalog) |
| Reasoning efforts | The model's efforts from the catalog | The model's efforts from the catalog | No None; some models add Max, and some have their own default |
| Anthropic authentication | ANTHROPIC_API_KEY only | ANTHROPIC_API_KEY or a connected Claude account | Not applicable (cannot run those models) |
| OpenAI authentication | OPENAI_API_KEY or a connected ChatGPT account | Not applicable (cannot run those models) | OPENAI_API_KEY or a connected ChatGPT account |
| xAI authentication | XAI_API_KEY or a connected SuperGrok account | Not applicable (cannot run those models) | Not applicable (cannot run those models) |
| Repository instruction files | The repository's .opencode/ directory and .openinspect/setup.sh | Reads the repository's CLAUDE.md natively; loads .claude/ settings, hooks, and agents. In a multi-repository session, settings and hooks come from the primary repository only; the other repositories contribute skills, commands, and agents | Reads the repository's AGENTS.md natively; refuses a repository .codex/config.toml |
| Sub-agents | The task tool; the timeline groups a sub-agent's activity under it | The Agent tool; returns only when the sub-agent has finished, grouped in the timeline the same way | None (Codex's multi-agent feature is disabled); child sessions still work |
| Follow-up prompts | Queue until the running turn completes | Queue until the running turn completes | Queue until the running turn completes |
| Resume after a sandbox restore | By session id | By session id | By Codex thread id |
| Personal MCP servers | On runtime generation 80 or later | On runtime generation 80 or later | Not loaded; each prompt records an mcp warning naming them |
Installation default Anthropic account
A default Claude account set under Settings › Accounts (provider accounts) takes effect only on
Claude Agent sessions, including automations and Linear, Slack, and GitHub sessions configured for
Claude Agent. OpenCode sessions, and the bot and integration sessions that run on OpenCode, keep
using ANTHROPIC_API_KEY, so setting a default never breaks a session that cannot use it.
Choose a harness in the composer
- Open the model control in the new-session composer. It reads
<harness>: <model> <effort>. - Choose Agent, then OpenCode, Claude Agent, or Codex. Your last choice is remembered for the next new session.
- Choose Model. The list is filtered to enabled models the chosen harness can run. If none of the enabled models can run on the harness, the composer says so, for example
No enabled models can run on Codex., and blocks submission until you enable one or switch harness. - Choose Effort if the model supports it, then send your prompt. The efforts listed are the ones the model offers on the chosen harness.
Switching harness drops any provider authentication pin the new harness cannot honor (for example a connected Claude account selected for a session you then switch to OpenCode), so you never submit a selection the server would refuse.
Once the session exists, the Agent row disappears. Per-message model overrides on the session page are limited to models the harness can run; an override outside that set is rejected with an error such as Model "openai/gpt-5.5" cannot run on the Claude Agent harness. rather than replaced.
Claude Agent sessions
Claude Agent runs Anthropic models through the Claude Agent SDK inside the sandbox. It is the harness that can use a connected Claude subscription instead of an API key.
Model availability under a Claude subscription is controlled by Anthropic. Confirm the account you connect can use the selected model before rolling it out broadly.
How the credential reaches the sandbox
- The session's Anthropic authentication choice (a connected account or the API key) is fixed when the session is created, before any sandbox starts.
- The platform holds the credential. Nobody signs in inside a sandbox, and the token is never shown in the browser.
- On every start of the agent (fresh spawn, supervised restart, or snapshot restore), the sandbox fetches the token from the control plane and keeps it in memory only. Nothing is written to disk, so a snapshot carries no credential and a restore fetches again.
- The
claudeprocess sees the ordinary sandbox environment (user secrets, proxies, session context) plus exactly one Anthropic credential: the connected account's token in account mode, orANTHROPIC_API_KEYin key mode, never both. OpenCode, code-server, the terminal, and user shells never see the Claude token.
Code the agent runs from Bash, and any hooks the repository's .claude/ settings register, run as children of the claude process and inherit its environment. That is the same exposure as the sandbox token and user secrets under any harness.
Tools served to the agent
OpenInspect's own tools are served to Claude Agent in-process as the oi MCP server:
| Tool | Available |
|---|---|
Child session tools (spawn-child, send-child-prompt, get-child-status, cancel-child) | Always |
upload-media | Always |
create-pull-request | When the session has a repository |
slack-notify | When agent notifications are enabled for the repository |
Session MCP servers configured under Settings › MCP Servers are passed through, except that a routed server points at OpenInspect's proxy. A turn that may use personal MCP servers restarts the agent process with them.
Sub-agents
Background sub-agents are disabled. An Agent tool call returns only when its sub-agent has finished, and several sub-agents launched in one message still run concurrently. This keeps a turn from ending before delegated work is done. As a second guard, the harness ignores the result of any turn it did not submit.
Privacy settings
The harness disables the underlying agent's commit, pull request, and session-link attribution. It also disables nonessential Anthropic traffic, error reporting, feedback and surveys, and both Anthropic and OpenTelemetry usage telemetry. Model requests and OpenInspect's own per-turn cost accounting are unaffected.
Skills and repository settings
Managed skills and the bundled skills are staged in a per-sandbox Claude configuration directory (~/.openinspect/claude/skills). The repository's .claude/ settings, hooks, and agents load from the project, the same trust boundary as .openinspect/setup.sh and .opencode/ under OpenCode. See Managed skills.
Cost reporting
Claude Agent reports the SDK's client-side cost estimate per turn (the running total at turn end minus the total at turn start, reset when the agent process restarts). Under a subscription the figure is informational, but a session spend limit still applies to it as configured. See Spend limits.
When a bound Claude account changes
| Change in Settings › Accounts | Effect on sessions bound to that account |
|---|---|
| Disable | The next prompt fails before a sandbox spawns, with guidance to reconnect the account. The next start of the agent on any bound session is refused. |
| Archive | The next prompt fails with guidance to start a new session with another account or an API key. An archived account cannot be reconnected. |
| Reconnect | The account stays active with the new credential. Bound sessions carry on, and their next agent start fetches the new token. |
| Recorded expiry approaching | The account is fenced to Reconnect required; the next prompt fails with reconnect guidance. |
In every case a sandbox that already holds a token keeps it in memory until it exits (inactivity timeout, hard timeout, or a stop), so a turn already running finishes on the old token. To end that sooner, stop the session from the session page. A runtime authentication failure fails the prompt with reconnect guidance and posts an error event; quota and rate-limit warnings keep the account active and appear on the timeline.
Codex sessions
Codex runs OpenAI models through OpenAI's Codex CLI inside the sandbox, on every sandbox provider. The runtime always launches the Codex CLI version pinned in the sandbox image, so an image built before Codex shipped must be rebuilt before Codex sessions can start on it.
Strict selection
Codex never swaps a selection it cannot honor for a default. A model it cannot run, a reasoning effort the model does not offer on Codex, a model disabled under Settings › Models, or a credential mode it cannot use is refused with an error when the session is created, when a prompt is sent or dispatched, and when an automation or integration starts a session. Fix the selection and try again.
How the credential reaches the sandbox
- The session's OpenAI authentication choice (a connected ChatGPT account or
OPENAI_API_KEY) is fixed when the session is created. The legacyOPENAI_OAUTH_*secrets are not used. - With a connected account, the sandbox fetches a short-lived access token from the control plane before every turn, and again whenever Codex asks for a refresh. Codex keeps the OpenAI credential in memory only, so it is never written to Codex's state directory or captured in a snapshot. A session stays bound to the ChatGPT workspace it started with.
- The
codexprocess does not inherit the sandbox'sOPENAI_*orCODEX_*environment variables; the credential is handed to Codex directly. Custom OpenAI endpoints are not supported: secrets such asOPENAI_BASE_URL,OPENAI_API_BASE, orCODEX_API_ENDPOINTare dropped before a Codex sandbox starts, so Codex uses the standard OpenAI endpoint. If one of those variables is set in the sandbox's runtime environment instead (for example by the image), Codex refuses to start. - Codex runs with no approval prompts and without its own command sandbox. The OpenInspect sandbox is the isolation boundary, as under the other harnesses.
Tools, MCP servers, and skills
- Codex gets the same OpenInspect tools as Claude Agent (child session tools,
upload-media,create-pull-request,slack-notify), under the same conditions, as Codex tools in anoinamespace. - Session MCP servers configured under Settings › MCP Servers are translated to Codex's own server configuration. A server named
oi, or a remote server whose URL carries credentials, a query string, or a fragment, is refused; put credentials in headers instead. Personal MCP servers are not loaded, because Codex binds MCP servers once per thread; each prompt records anmcpwarning naming them. - Managed skills and the bundled skills are staged under the per-sandbox Codex directory (
~/.openinspect/codex/skills), and Codex reads the repository'sAGENTS.mdnatively. - A repository
.codex/config.tomlis not supported, because it can reroute credentials and register hooks: Codex refuses to run in a repository that has one. Move MCP servers to Settings › MCP Servers and instructions toAGENTS.md. - Codex's own hooks, plugins, apps, memories, and multi-agent features are disabled, as are its analytics, feedback, update checks, and history file.
Tasks, errors, and warnings
- Each plan update Codex publishes replaces the Tasks list in the session's right sidebar, with pending, in-progress, and completed steps, the same as a task list from the other harnesses.
- Codex errors and warnings appear on the timeline. An error Codex is retrying shows as a warning; a failed turn shows Codex's reason, with guidance for common causes such as an unauthorized credential, a usage or rate limit, or a conversation that no longer fits the context window. Configuration warnings, model reroutes, and OpenAI rate limits that are reached or nearly used up also appear as warnings.
Cost reporting
Codex prices each model request from the model price list cached in the sandbox image. Under a ChatGPT subscription the figure is informational, but a session spend limit still applies to it as configured. A model missing from the price list is recorded at $0 with a timeline warning. See Spend limits.
Troubleshooting
Next steps
Choosing a model and reasoning effort
Enable models for your workspace, pick a model and effort in the composer, and understand which credential each provider needs.
Provider accounts and API keys
Connect ChatGPT, SuperGrok, and Claude subscriptions as installation-wide provider accounts, set defaults for unattended sessions, and manage account lifecycle.