OpenCodex Proxy Operations

Operating ocx

ocx supports local configuration and named live management workflows. Coverage is per task: provider edits, account selection, model visibility, routing reads, client integration controls and diagnostics have different transports and limits. A shared API prefix does not prove that every dashboard action has a CLI equivalent.

This skill is for operating a proxy. AGENTS_INSTALL.md covers installation and operating consent; the repository AGENTS.md covers code changes.

Find the task offline

Start at the smallest useful level; no running proxy is needed for help:

ocx help                         # compact root
ocx help models                  # family and declared children
ocx help models preset show      # exact leaf, when declared
ocx help --all                   # full top-level reference, when needed

Then read only the matching task chapter. For example, use providers/models for catalog work or Lab for local evidence. Use ocx help <family> <leaf> or appended --help, not a trailing bare help after nested operands. Missing detail can fall back to family help; it is not proof that a runtime operation is absent.

For a route you already know, an optional lookup is:

ocx capabilities --route '/api/providers/{provider}/model-costs' --json

This matches the declared path template, not a concrete provider URL or HTTP method. Exit 4 means no declaration matched. Full ocx capabilities --json and --mutating-only --json are useful for broad inventories, not mandatory preflight. Declarations describe the installed CLI; actual handlers remain the grammar authority.

Choose a workflow

Start with the named read or preview, then follow its recipe. Help is offline; the target column describes execution. A listed write still needs authority for that task, and read-oriented probes can contact upstream services.

These are task entry points, not a count of GUI parity. Native window focus, browser presentation and session-only actions retain their own interfaces. Grant inspection does not authorize grant consumption; persisted local Desktop export does not export an unsaved dashboard draft.

Before live management work

1. ocx ready --json checks readiness (ready, pending, failed, unreachable).
2. ocx status --json checks the target and versionSkew.relation. unknown is not a confirmed match; a mismatch needs the intended installation resolved.
3. Run the task with --json only when that leaf supports it. ocx doctor rejects it; ocx v2 supports JSON for both local and explicit live targets.

These checks do not require starting a proxy for offline help, local provider configuration, config validation or local Lab inspection. On a connected client, ordinary management commands do not automatically target the hub: perform them on the hub or use its dashboard. See remote targeting.

Inspect both the exit code and receipt. Saved config, runtime application, client file convergence, skipped work and partial completion are different outcomes; read back the relevant setting after a write. Exit 0 also covers previews and intentional no-ops. Management failures normally print stderr prose even with --json; usage codes include 2 and legacy 64 exceptions for capabilities, ready, and resolve. See JSON shapes and failure semantics before scripting recovery.

Observation and explicit-key API tasks

For request/injection follow, timeline exclusions and scoped usage, start with observation recipes. Use versioned log events to reconstruct observed windows; row JSONL cannot express removals. Neither stream guarantees lossless traffic history.

Selected-key model/audio tasks are separate from management calls. They require explicit operator authorization for upstream calls/uploads and a private human terminal handoff for key input. Never collect the key in this agent session, argv or environment, and never substitute an admin/enrolled credential. Read the selected-key and audio recipe before proposing one. Reports are observations, not key-scope/billing certificates.

Consent: one thing you must not do

Do not star the repository on the user's behalf. ocx inspect star reads the status, and that is the entire CLI surface for it. The starring POST requires a dashboard session, so an ordinary admin-token management call cannot perform it. That is not a barrier against a determined local agent; the consent rule still binds every mechanism because it spends their GitHub identity. Do not route around it with gh, a direct HTTP call, or a minted session. If starring would be useful, say so and let the user decide.

The same boundary covers the session-gated /api/codex-prompt writes: read them with ocx inspect codex-prompt, and leave the writes to the dashboard.