OpenAI Codex (CLI)

OpenAI’s codex command-line tool is an alternative provider you can assign to any Viberia agent in place of Claude.

Setup

You install the codex CLI on your computer, sign it in to your OpenAI account once, and then point Viberia at the binary.

Prerequisites

• An OpenAI account with API access to the Codex models.
• A network connection — the CLI calls OpenAI’s API on every turn.
• Permission to install a global binary on your machine.

Install the CLI

Follow OpenAI’s current instructions for installing the codex CLI on your platform. Once installed, run it once from a normal terminal to sign in:

codex

Complete the auth flow. The CLI stores your credentials so Viberia doesn’t need to touch them.

Point Viberia at the binary

Open Settings → CLI Configuration. The Codex CLI path field (a CliPathField row) is where Viberia records the path. To find it:

which codex

Paste the output into the field and click Test. A green check confirms Viberia can invoke the binary; a red error means the path is wrong or the CLI isn’t installed.

Note: If you change the path while agents are running, restart Viberia so every agent picks up the new binary.

Configuration

Codex is selected the same way every other provider is: either as a role-tier default or as a per-agent override.

Role-tier defaults

In Settings → Agent Defaults, set a role tier’s default model to a Codex model. Newly created agents in that tier will spawn on Codex.

Per-agent override

In any agent’s chat window, open the Model & Tools cell above the composer and pick a Codex model from the dropdown.

Setting	Where	Default	Notes
Codex CLI path	Settings → CLI Configuration	platform default (e.g. codex on PATH)	Restart agents after changing.
Default model per role tier	Settings → Agent Defaults	provider’s recommended balance	Affects newly created agents only.
Per-agent model	Agent chat → Model & Tools	inherited from role tier	Takes effect next turn.
Reasoning effort	Agent chat → Model & Tools	provider default	See note below.

Note: TODO — verify in app. Exact reasoning-effort levels exposed for Codex (for example low / medium / high) should be confirmed against the current build before publishing this row.

Spawning agents on this provider

To put a specific agent on Codex, open its chat window, click the Model & Tools cell, and pick a Codex model. The change persists across restarts and takes effect on the agent’s next turn.

To make new agents in a role tier default to Codex, change the tier’s default in Settings → Agent Defaults. Agents already in the world keep their current model — only newly created ones inherit the new default.

Features

• Model selection — choose between Codex models supported by your Viberia build.
• Reasoning effort — Codex exposes a reasoning-effort dial. Higher effort produces deeper reasoning at higher token cost and longer latency.
• Skills (slash commands) — Codex agents invoke installed skills via /<name>.
• MCP — Codex agents can use MCP servers configured at the user, building, or agent scope.

Limitations

• Feature coverage trails Claude. Codex is supported as a chat provider, but advanced behaviors that depend on Claude-specific features may not be available. If a behavior breaks when you switch an agent from Claude to Codex, that’s expected — switch back or open the Troubleshooting page.

  Note: TODO — verify in app. Specifically confirm whether streaming tool calls and MCP fan-out (parallel MCP server invocation) are supported on Codex in the current build; both have been reported as Claude-only behaviors.

• Account required. Codex agent calls go to OpenAI’s API. You need an account in good standing and a valid sign-in on the codex CLI.
• Network required. No offline mode. Connection drops fail the agent’s current turn.
• API rate limits apply. Heavy parallel use can hit OpenAI’s per-account limits; the error surfaces in the agent’s chat as a failed turn.
• Token cost is your responsibility. Use the Token Tracker (toggle with Cmd+Shift+U) to keep an eye on usage; Codex is reported on its own line.
• Model availability tracks OpenAI. When OpenAI deprecates a Codex model, it disappears from Viberia’s dropdowns at the next app update. Per-agent overrides may need to be reset.

Related

• Installation & Setup — install the CLI and configure binary paths.
• Settings Overview — Settings dialog tour.
• Agent Chat — change a single agent’s model and reasoning effort.
• Anthropic Claude and Google Gemini — the other CLI providers.