CLI Agents, Routing, and Integrations

These commands control agent policy and routing, inspect the live proxy, and connect supported clients to opencodex.

Agent policy

`ocx agent <status|injection|effort|subagents|fallback|sidecar> ...`

Manage the headless multi-agent roster, effort caps, prompt injection, fallback, and sidecar settings. Use status for the current policy. See Sub-agent surfaces for how surface modes, delegation, effort, and fallback behavior fit together.

ocx agent subagents set ark/model-a,openai/gpt-5.5

ocx agent sidecar web --list and ocx agent sidecar vision --list print the models the server currently offers for each sidecar — the exact filtered set the dashboard picker shows (picker-visible rows plus the login-entitled Luna/Haiku auth slots, intersected with executor availability for web search, minus provably text-only models for vision). Human-readable lists show each model’s backend in brackets. A web-search --model write resolves that server-offered row and persists its backend and model together, so switching to an Anthropic option cannot keep an OpenAI backend (or vice versa). Writes go to the same management route as the GUI and are subject to the same per-sidecar gate: web search refuses a backend/model pair outside the listed set (closed membership), while vision refuses only a model provably unable to see (unknown ids stay writable).

ocx agent sidecar web --list
ocx agent sidecar web --model gpt-5.6-luna

`ocx effort [status|set|clear]`

Inspect or change main and subagent reasoning-effort caps through the live proxy, or the local configuration when no proxy is available. Cap values are low, medium, high, xhigh, max, and ultra; - clears the selected cap. none and minimal are not cap levels and are rejected before probing the proxy or submitting an update, including when another option in the same command is valid. They remain valid for --injection, which sets the separate injection effort rather than a cap.

ocx effort status --json
ocx effort set --main high --subagent low
ocx effort set --subagent -

Status preserves existing stored/runtime cap values and reports unsupported values in warnings (an empty array when none are unsupported). The same warnings appear in human output and name the field that is ignored with a correction command. Status never repairs or rewrites those values. An ignored subagent field does not remove a valid main cap. ocx effort clear clears both caps while retaining the separate injection-effort setting. See Sub-agent surfaces for the request surfaces where caps apply.

`ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>>`

Manage the Codex multi_agent_v2 feature flag and the three-state multi-agent surface mode.

Subcommand	Action
`status` (default)	Report the current v2 flag, multi-agent mode, and thread concurrency.
`on`	Enable the global `multi_agent_v2` feature and resync the catalog. Rejected while the v2 hybrid pin is active because the global override would defeat it.
`off`	Disable the `multi_agent_v2` feature and resync the catalog.
`mode v1`	Force all models to v1, disable native v2, and preserve the active thread limit.
`mode default`	Respect upstream model surface pins.
`mode v2`	Force models to v2 and preserve the active thread limit. With `keep-native-v1` off, enable global native v2; with it on, disable the global override and use catalog pins.
`keep-native-v1 on\|off`	Under `mode v2`, keep ChatGPT-native models on v1 and routed models on v2. Enabling it disables the global V2 override before catalog sync.
`threads <n>`	Set the active v1/v2 thread limit to an integer of at least 1.
`mode-hint <text>`	Set the Proactive delegation hint (Ultra mode) for every model and effort.
`mode-hint --clear`	Remove the hint so the effort-derived policy (ultra = proactive) resumes.

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 on
ocx v2 threads 16
ocx v2 mode-hint "Proactive multi-agent delegation is active."
ocx v2 mode-hint --clear

The mode subcommand writes multiAgentMode to the opencodex config and resyncs the Codex catalog. Mode and flag transitions move the current numeric thread limit between the valid v1/v2 Codex keys; a failed transition restores the original config.toml. Changes apply to new Codex sessions, while running sessions keep their pinned surface.

Codex resolves an enabled global multi_agent_v2 override before the selected model’s catalog pin. The hybrid keep-native-v1 contract therefore keeps that global override off; otherwise a native row stamped v1 would still start on V2 and produce backend-encrypted child tasks.

mode-hint writes features.multi_agent_v2.multi_agent_mode_hint_text in Codex’s $CODEX_HOME/config.toml even when multi_agent_v2 is currently disabled. The command only persists the override; it does not enable or disable the feature, so the hint takes effect when a matching Codex surface is active. The hint overrides codex-rs’s effort-derived multi-agent policy, so any model and any reasoning effort receives the Proactive delegation prompt. It does not change reasoning effort itself. A missing argument or a whitespace-only value is rejected; only --clear removes the hint. The Subagents dashboard’s Ultra mode on toggle has a stricter gate: it requires the native feature to be enabled with an explicit v2 surface (ocx v2 mode v2); ocx v2 on alone does not satisfy that dashboard gate.

Combo routing

`ocx combo <list|show|set|remove> ...` · `ocx route combo ...`

Manage combo failover and round-robin virtual models. ocx route combo is the hierarchical alias; combo is currently the supported routing resource. Targets use provider/model[:weight],provider/model[:weight].

ocx combo list
ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5

set accepts --strategy, --sticky, --effort, --alias, --rename-from, --native-alias, and --display-name <label|-> (- clears the label). A native alias captures only one currently supported, unqualified bare OpenAI model id. Bare gpt-5.6-* native aliases use Codex Pool/Direct credentials. Account-qualified OpenAI routes remain distinct, while provider-qualified routes such as openai-apikey/gpt-5.6-* use their configured API key and never fall through to the native alias. Read the safety and visibility contract in the guide before enabling the compatibility pair.

See Combos for routing behavior and configuration guidance.

Observability and debug

`ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...`

Inspect proxy requests, usage, storage, memory, and debug data. The direct aliases are:

Alias	Equivalent resource
`ocx logs [filters] [–follow] [–json	–jsonl]`
`ocx usage [–range <today	1d
`ocx storage [--json]`	`ocx observe storage`
`ocx memory [--json]`	`ocx observe memory`

ocx observe usage --range 30d --json
ocx usage --since 2026-09-01T09:00:00Z --until 2026-09-01T10:59:59.999Z --json

--since and --until must be supplied together. They accept integer epoch milliseconds or full ISO datetimes with an explicit timezone, include both endpoints, and override --range. Invalid or reversed bounds fail before the request. Human output prints the requested interval; --json includes customWindow, since, and until. Existing surface/provider/model filters still apply. These commands query the running proxy; they do not provide offline reports.

--range today (alias 1d) reports the current local day. --provider and --model narrow the report to one upstream target — distinct from --surface, which selects the calling client (Codex, Claude Code, Grok) rather than the provider serving the request.

The default view prints request, token and estimated-cost totals plus per-provider and per-model breakdowns. Costs are API list-price equivalents, not a billing receipt: subscription plans and provider credits are billed separately, and requests with no matching price row are counted as unpriced/unmetered rather than folded in as zero.

ocx usage --range today --provider xai

When some usage records cannot be included, human output warns, including when there are zero readable rows. Any displayed totals reflect readable records only. If a filter has no readable matches, the output shows the warning and guidance instead of total lines; skipped records may contain matches. --json preserves the response-level usageIncomplete diagnostic and reason.

`ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>`

Read or change runtime debug overrides through the running proxy’s management API.

ocx debug provider on|off|status|reset
ocx debug provider logs [-f|--follow]
ocx debug usage on|off|status|reset
ocx debug usage logs [-f|--follow]

With no scope, ocx debug prints usage and, when the proxy is stopped, the next-start environment defaults. Provider debug defaults from OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES=1 also works); usage debug defaults from OPENCODEX_USAGE_DEBUG=1.

API access

`ocx access <key|endpoints|models|test> ...`

Manage OpenCodex admission API keys and inspect external endpoints and models. ocx api-key <list|create|remove> ... is an alias of ocx access key.

ocx access key create deployment

Client integrations

`ocx integration <claude|grok> ...`

Manage supported Claude and Grok integrations. The direct command families below expose their client-specific controls.

`ocx claude [claude args...]`

Ensure the proxy is running, then launch Claude Code with ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, and model slots from config.claudeCode. Routed models appear in the native /model picker through stable slot aliases with Claude Code 2.1.129 or newer. On older versions, select with ANTHROPIC_MODEL or /model <id>. User-exported ANTHROPIC_* variables always take precedence.

Claude Desktop profile commands are:

ocx claude desktop [apply]                         Save and apply the four-family profile
ocx claude desktop show [--json]                   Show routes, families, and defaults
ocx claude desktop status [--json]                 Show applied state, drift, and health
ocx claude desktop move <route> <family> [--default]
ocx claude desktop default <family> <route|none>
ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)
ocx claude desktop import <path> [--apply]         Validate and import JSON

The families are opus, fable, sonnet, and haiku; new routes start in opus. none is valid only when that family is empty. Legacy apply flags --static, --hybrid, and --discovery-only remain supported. Use ocx claude config <status|set> ... for Claude Code settings.

`ocx opencode [opencode args...]`

Ensure the proxy is running, then launch opencode with the generated provider.opencodex and providers.opencodex blocks in OpenCode’s inline runtime layer (OPENCODE_CONFIG_CONTENT). The legacy block keeps V1 clients working; the V2 block is the one carrying the selectable reasoning-effort variants. Existing inline config is preserved and only those two keys are replaced for this launch. Global or project opencode.json files may be read to warn about an existing override, but on-disk files are never modified. Routed models appear as opencodex/<provider>/<model>. Launching plain opencode later behaves exactly as before.

`ocx grok <status|exclude|include|set|clear|apply> ...`

Manage and apply the Grok Build model fence.

Client config export

`ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo>`

Print a client config wired to the running proxy. The command serializes the opencodex provider block — base URL, model list, and the client’s credential reference or loopback placeholder — in the selected client’s native format.

The proxy must be running; the command resolves its live port, reads /api/models, and emits only models Codex can currently see.

Flag	Action
`--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>`	Required. Selects the client config dialect.
`--json`	Print the generated document as JSON on stdout for scripts. This is JSON even when the selected client’s native format is YAML, TOML, or JSON5.
`--out <path>`	Write the client’s native config format to `<path>`. Refuses to replace an existing file.
`--force`	Allow `--out` to replace an existing file.

ocx export --client opencode                     # config plus destination, merge warning, and counts
ocx export --client pi --json > pi-models.json   # JSON document for a pipe or a diff
ocx export --client omp --out ./omp-models.yml    # native OMP YAML
ocx export --client opencode --out ~/opencodex-opencode.json

Without --json the generated config leads, then the canonical destination path, the merge warning, the env export line where the client has one, and a model count with how many rows omit context limits (the client applies its own defaults for those).

Client	Canonical destination	Download filename	Env var
`opencode`	`~/.config/opencode/opencode.json` (`XDG_CONFIG_HOME` wins when set)	`opencode.json`	`OPENCODEX_OPENCODE_API_KEY`
`pi`	`~/.pi/agent/models.json` (`PI_CODING_AGENT_DIR` wins when set; a relative value is refused)	`pi-models.json`	none — the block carries the literal `opencodex-loopback`
`omp`	`~/.omp/agent/models.yml` (`OMP_PROFILE` wins over `PI_PROFILE`, even when empty; named profiles use the home-relative `PI_CONFIG_DIR` directory name and ignore `PI_CODING_AGENT_DIR`, while the default profile lets `PI_CODING_AGENT_DIR` win)	`omp-models.yaml`	none — loopback placeholder
`hermes`	`~/.hermes/config.yaml`	`hermes-config.yaml`	`OPENCODEX_HERMES_API_KEY`
`openclaw`	`~/.openclaw/openclaw.json`	`openclaw.json5`	`OPENCODEX_OPENCLAW_API_KEY`
`kimi`	`~/.kimi-code/config.toml`	`kimi-config.toml`	none — loopback placeholder
`gajae`	`~/.gjc/agent/models.yml`	`gajae-models.yaml`	`OPENCODEX_GAJAE_API_KEY`
`dsh`	`$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`)	`settings.yaml`	none — non-secret loopback bearer placeholder
`mcode`	`~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, then the legacy `MAVIS_DATA_DIR`, win when set; a relative value is refused)	`mcode-config.yaml`	none — loopback placeholder
`zcode`	`~/.zcode/v2/config.json` (`ZCODE_DATA_DIR` wins when set; a relative value is refused)	`config.json`	none — loopback placeholder
`prime`	`~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` wins when set; a relative value is refused)	`prime-models.json`	none — loopback placeholder
`aside`	`~/.aside/u/<account>/models.json` for the account Aside’s own `accounts.json` names as current; an unreadable manifest is refused rather than defaulting to an account	`aside-models.json`	none — loopback placeholder
`raycast`	`~/.config/raycast/ai/providers.yaml` on macOS and Windows alike (Raycast does not honor `XDG_CONFIG_HOME`)	`raycast-providers.yaml`	none — loopback only, no `api_keys` entry is written
`omo`	`~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, then `SENPI_CODING_AGENT_DIR`, then `PI_CODING_AGENT_DIR` win in that order when set; a relative value is refused)	`omo-models.json`	none — loopback placeholder

The managed DSH export requires DSH 0.1.0-rc.6 or newer and owns only llm-pi-ai.providers.opencodex. DSH hot reloads that provider; the user’s default model and deepseek-official remain untouched. This export is loopback-only and carries no real credential.

opencode interpolates {env:OPENCODEX_OPENCODE_API_KEY}. The generated Pi and OMP exports do not require an environment variable: each carries the literal opencodex-loopback placeholder. This is load-bearing because both clients resolve apiKey while building their model lists and hide the whole provider when an existing config contains an unset env reference. The proxy never checks the generated placeholder on loopback. OMP supports provider-level headers, but this initial integration deliberately remains loopback-only; remote x-opencodex-api-key wiring is deferred.

The Raycast export is a standalone providers.yaml document with one id: opencodex element in the providers sequence: name: OpenCodex, the proxy’s /v1 base URL, and every routed model with its abilities (tools and system_message always supported, vision from the catalog’s input modalities, reasoning_effort when the model has an effort ladder, temperature off for reasoning models). Custom Providers is a Raycast Pro feature, and Raycast watches the file, so a saved change takes effect without a restart. The format is documented at manual.raycast.com/ai/custom-providers. No api_keys entry is written, so this export is loopback-only and a non-loopback bind is refused.

The MCode, ZCode and Prime exports are loopback-only for the same reason and likewise carry the opencodex-loopback placeholder rather than a real credential. Prime Agent reads the same models.json contract Pi does, so the two exports produce the same document; only the destination differs. A relative path in any of those three environment overrides is refused, because the proxy and the client can have different working directories and would otherwise disagree about which file is meant.

ZCode 3.8.1 may save runtime-derived reasoning, limit.output, and default context metadata back into the generated provider.opencodex.models entries. Managed integration status treats only those documented additions as refreshable drift. Provider identity and connection settings, including options.baseURL, model membership, names, modalities, and any context limit OpenCodex emitted authoritatively remain protected; editing them reports conflict / foreign-edit instead of overwriting the file. An ownership record created by an older OpenCodex version can recover automatically when the generated catalog is otherwise unchanged. If both the catalog and the block changed, re-apply only after reviewing the file because the older record cannot prove which change was ZCode-derived.

No key is ever serialized. Configs carry either a documented environment reference or a non-secret loopback placeholder. A loopback proxy (127.0.0.1, the default) requires no admission key at all. Set a referenced variable only when the client schema supports it and the proxy binds beyond loopback; see Remote access for how admission keys are issued. Keys for the upstream providers themselves are a separate thing entirely, configured per Providers. gjc is the exception: OPENCODEX_GAJAE_API_KEY fills its provider credential from the environment, but its schema cannot send the remote admission header, so the generated gjc integration remains loopback-only.

The same payload is served by GET /api/client-config and rendered on the dashboard’s API tab, so the CLI, the API, and the GUI use the same bytes.

Runtime and configuration

`ocx system <status|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...`

Manage headless runtime settings, startup, sync, diagnostics, and updates.

ocx system codex-restart --yes restarts Codex app-servers and fully quits and relaunches the Codex desktop app, through the same module as ocx sync --restart-codex. When the proxy itself is running inside the Codex app, the command refuses with an actionable message instead of promising a handoff it cannot complete.

ocx system settings --stream-mode eager-relay

ocx system update updates OpenCodex itself. The separate Codex CLI inspection surface is:

ocx system codex-cli-update check --json

check makes no package-registry request and inspects bounded configured-candidate provenance evidence, including a redacted executable location and ownership evidence. Trusted published-launcher context authenticates the candidate snapshot, not successful Codex execution. Because this one-shot command never executes Codex, environment and persisted candidates remain report-only (managed: false, normally selection_unattested); selectionAttested remains false. The JSON report exposes candidateAvailable, candidateVersion, candidateSource, and selectionAttested. Inspecting the configured candidate requires a trusted published-launcher context; a direct Bun/source launch has no such proof, ignores ambient and persisted candidate state, and may report candidate_unavailable on POSIX. On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed. Because that slice never consults persisted state, a Windows run with no captured environment candidate reports windows_inspection_deferred rather than candidate_unavailable: the command cannot observe whether a Codex CLI is installed, so it reports the deferral instead of asserting that no candidate exists. The command does not execute Codex or a package manager, repair a shim, write configuration or cache state, stop a process, or install anything. App-bundled, recognized version-manager, unverified standalone, and ambiguous shim states are reported as unmanaged or unknown and are never classified as managed.

On Windows, a captured bare command such as CODEX_CLI_PATH=codex, a remote path, or a device path reports candidate_path_unavailable instead. Those cases have a captured candidate; its path is not eligible for this inspection.

`ocx config <show|get|set|unset|validate|export|import> ...`

Inspect and safely modify validated OpenCodex configuration. show and get mask secrets. Import validates before writing and requires --yes.

Usage from a connected client

ocx usage reads the connected hub with this client’s enrolled data key. Human output identifies the hub source and client-key scope; --json returns the same scoped data. Range, surface, provider/model filters and custom --since/--until bounds remain available. Account breakdowns and other clients’ records are not shared. An old or unavailable hub produces an explicit error instead of substituting local usage; upgrade the hub if it does not support this read.

The read-only data-plane endpoint is GET /v1/usage, using x-opencodex-api-key with a configured client key. Environment-wide and admin keys are refused. It accepts range, surface, provider, model, since, and until; unknown/repeated options and caller-selected key IDs are rejected. Oversized skipped rows retain the explicit incomplete-history warning.

CLI Agents, Routing, and Integrations

Agent policy

ocx agent <status|injection|effort|subagents|fallback|sidecar> ...

ocx effort [status|set|clear]

ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>>

Combo routing

ocx combo <list|show|set|remove> ... · ocx route combo ...

Observability and debug

ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...

ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>