CLI 에이전트, 라우팅, 통합

이 명령들은 에이전트 정책과 라우팅을 제어하고, 실행 중인 프록시를 검사하며, 지원되는 클라이언트를 opencodex에 연결합니다.

에이전트 정책

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

헤드리스 멀티 에이전트 목록, effort 상한, 프롬프트 주입, fallback, sidecar 설정을 관리합니다. 현재 정책은 status로 확인합니다. surface mode, delegation, effort, fallback 동작이 어떻게 맞물리는지는 Sub-agent surfaces를 보십시오.

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

`ocx effort [status|set|clear]`

실행 중인 프록시를 통해 메인·서브에이전트의 reasoning-effort 상한을 조회하거나 변경하며, 프록시가 없으면 로컬 설정을 사용합니다. 상한은 low, medium, high, xhigh, max, ultra이고, -는 해당 상한을 해제합니다. none과 minimal은 상한 단계가 아니므로 같은 명령의 다른 옵션이 유효하더라도 프록시 탐색이나 설정 변경 요청 전에 거부됩니다. 두 값은 상한이 아닌 별도의 injection effort를 설정하는 --injection에서는 그대로 사용할 수 있습니다.

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

상태 조회는 저장값 또는 런타임 상한 원문을 보존하고, 지원하지 않는 값은 warnings에 표시합니다 (모두 지원되는 값이면 빈 배열). 일반 출력에도 같은 경고가 나오며, 무시되는 필드와 수정 명령을 안내합니다. 상태 조회가 기존 값을 자동으로 복구하거나 덮어쓰지는 않습니다. 서브에이전트 필드가 무시되더라도 유효한 메인 상한이 사라지는 것은 아닙니다. ocx effort clear는 별도의 injection-effort 설정을 유지하면서 두 상한을 해제합니다. 상한이 적용되는 요청 surface는 Sub-agent surfaces를 참고하세요.

`ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>`

Codex multi_agent_v2 기능 플래그와 세 상태 멀티 에이전트 surface mode를 관리합니다.

하위 명령	동작
`status` (기본값)	현재 v2 플래그, 멀티 에이전트 모드, thread 동시성을 보고합니다.
`on`	`multi_agent_v2` 기능을 켜고 catalog를 다시 동기화합니다.
`off`	`multi_agent_v2` 기능을 끄고 catalog를 다시 동기화합니다.
`mode v1`	모든 모델을 v1으로 고정하고, native v2를 끄며, 활성 thread 한도를 유지합니다.
`mode default`	업스트림에서 지정한 model surface pin을 따릅니다.
`mode v2`	모든 모델을 v2로 고정하고, native v2를 켜며, 활성 thread 한도를 유지합니다.
`threads <n>`	활성 v1/v2 thread 한도를 1 이상의 정수로 설정합니다.

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 on
ocx v2 threads 16

mode 하위 명령은 multiAgentMode를 opencodex config에 쓰고 Codex catalog를 다시 동기화합니다. mode와 flag 전환은 현재 숫자 thread 한도를 유효한 v1/v2 Codex key 사이로 옮깁니다. 전환이 실패하면 원래의 config.toml이 복원됩니다. 변경은 새 Codex 세션에만 적용되고, 실행 중인 세션은 고정된 surface를 유지합니다.

콤보 라우팅

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

콤보 failover와 round-robin 가상 모델을 관리합니다. ocx route combo는 계층형 별칭이며, 현재 지원되는 라우팅 리소스는 combo입니다. 대상은 provider/model[:weight],provider/model[:weight] 형식을 사용합니다.

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

라우팅 동작과 설정 안내는 Combos를 보십시오.

관측성과 디버그

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

프록시 요청, 사용량, 저장소, 메모리, 디버그 데이터를 확인합니다. 직접 별칭은 다음과 같습니다:

별칭	대응 리소스
`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

일부 사용량 기록을 집계하지 못하면 일반 출력은 읽을 수 있는 행이 없어도 경고합니다. 표시되는 합계는 읽을 수 있는 기록만 반영합니다. 필터에 일치하는 읽을 수 있는 기록이 없으면 합계 항목 대신 경고와 안내를 표시하며, 제외된 기록에는 일치하는 항목이 있을 수 있습니다. --json은 응답의 usageIncomplete 진단과 사유를 그대로 유지합니다.

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

실행 중인 프록시의 관리 API를 통해 런타임 디버그 override를 읽거나 변경합니다.

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]

scope를 지정하지 않으면 ocx debug는 사용량을 출력하고, 프록시가 중지된 상태라면 다음 시작 시의 환경 기본값도 함께 보여줍니다. provider 디버그의 기본값은 OCX_DEBUG=1에서 오며(OCX_DEBUG_FRAMES=1도 예전 방식으로 동작합니다), usage 디버그의 기본값은 OPENCODEX_USAGE_DEBUG=1에서 옵니다.

API 접근

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

OpenCodex admission API key를 관리하고 외부 endpoint와 model을 검사합니다. ocx api-key <list|create|remove> ...는 ocx access key의 별칭입니다.

ocx access key create deployment

클라이언트 통합

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

지원되는 Claude 및 Grok 통합을 관리합니다. 아래의 직접 명령군이 클라이언트별 제어를 제공합니다.

`ocx claude [claude args...]`

프록시가 실행 중인지 확인한 뒤, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, 그리고 config.claudeCode의 모델 슬롯을 사용해 Claude Code를 실행합니다. 라우팅된 model은 Claude Code 2.1.129 이상에서 안정적인 slot alias를 통해 기본 /model 선택기에 나타납니다. 더 오래된 버전에서는 ANTHROPIC_MODEL 또는 /model <id>로 선택합니다. 사용자가 내보낸 ANTHROPIC_* 변수는 항상 우선합니다.

Claude Desktop 프로필 명령은 다음과 같습니다:

ocx claude desktop [apply]                         Save and apply the four-family profile
ocx claude desktop show [--json]                   Show routes, families, and defaults
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

family는 opus, fable, sonnet, haiku이며, 새 route는 opus에서 시작합니다. none은 해당 family가 비어 있을 때만 유효합니다. 레거시 apply 플래그인 --static, --hybrid, --discovery-only도 계속 지원합니다. Claude Code 설정은 ocx claude config <status|set> ...를 사용하십시오.

`ocx opencode [opencode args...]`

프록시가 실행 중인지 확인한 뒤, OpenCode의 인라인 런타임 계층(OPENCODE_CONFIG_CONTENT)에 생성된 provider.opencodex 및 providers.opencodex 블록을 넣어 opencode를 실행합니다. 기존 인라인 config는 유지되고, 이번 실행에서는 이 두 키만 교체됩니다. 전역 또는 프로젝트 opencode.json 파일은 기존 override가 있는지 경고하기 위해 읽을 수 있지만, 디스크상의 파일은 절대 수정하지 않습니다. 라우팅된 model은 opencodex/<provider>/<model>로 나타납니다. 이후 plain opencode를 실행하면 이전과 정확히 같은 방식으로 동작합니다.

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

Grok Build model fence를 관리하고 적용합니다.

클라이언트 설정 내보내기

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

실행 중인 프록시에 연결할 client config를 출력합니다. 이 명령은 base URL, model list, 그리고 client에 따라 credential reference 또는 opencodex-loopback placeholder를 포함한 opencodex provider block을 선택한 client의 네이티브 형식으로 직렬화합니다.

프록시는 실행 중이어야 합니다. 이 명령은 실제 포트를 확인하고, /api/models를 읽고, 현재 Codex가 볼 수 있는 model만 내보냅니다.

플래그	동작
`--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside\|raycast\|omo>`	필수입니다. 클라이언트 설정 형식을 선택합니다.
`--json`	config JSON만 stdout에 출력하므로, redirect가 byte-exact 출력을 캡처합니다. `--out` write note를 포함한 모든 진단 메시지는 stderr로 갑니다.
`--out <path>`	config를 `<path>`에 씁니다. 기존 파일이 있으면 덮어쓰지 않습니다.
`--force`	`--out`이 기존 파일을 덮어쓰도록 허용합니다.

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

--json이 없으면 선택한 client의 네이티브 형식으로 생성된 config가 먼저 나오고, 그다음 표준 대상 경로, merge 경고, 해당 client에 env 변수가 있는 경우 env export 줄, 그리고 context limit을 생략한 row 수를 포함한 model count가 이어집니다(이 경우 client는 자체 기본값을 적용합니다).

클라이언트	표준 대상 경로	다운로드 파일명	환경 변수
`opencode`	`~/.config/opencode/opencode.json` (`XDG_CONFIG_HOME`이 설정되어 있으면 우선합니다)	`opencode.json`	`OPENCODEX_OPENCODE_API_KEY`
`pi`	`~/.pi/agent/models.json` (`PI_CODING_AGENT_DIR`가 설정되면 우선. 상대 경로는 거부됩니다)	`pi-models.json`	없음 - 블록에 리터럴 `opencodex-loopback`이 들어갑니다
`omp`	`~/.omp/agent/models.yml` (기본값. 빈 값이어도 `OMP_PROFILE`이 `PI_PROFILE`보다 우선합니다)	`omp-models.yaml`	없음 - 리터럴 `opencodex-loopback`
`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`	없음 - loopback placeholder
`gajae`	`~/.gjc/agent/models.yml`	`gajae-models.yaml`	`OPENCODEX_GAJAE_API_KEY`
`dsh`	`$DSH_HOME/settings.yaml`(기본값 `~/.dsh/settings.yaml`)	`settings.yaml`	없음 — 비밀이 아닌 loopback bearer placeholder
`mcode`	`~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, 그다음 레거시 `MAVIS_DATA_DIR`가 설정되면 우선. 상대 경로는 거부됩니다)	`mcode-config.yaml`	없음 — loopback placeholder
`zcode`	`~/.zcode/v2/config.json` (`ZCODE_DATA_DIR`가 설정되면 우선. 상대 경로는 거부됩니다)	`config.json`	없음 — loopback placeholder
`prime`	`~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR`가 설정되면 우선. 상대 경로는 거부됩니다)	`prime-models.json`	없음 — loopback placeholder
`aside`	`~/.aside/u/<account>/models.json`. Aside의 `accounts.json`이 현재 계정으로 지정한 account를 사용합니다. 매니페스트를 읽을 수 없으면 임의의 계정으로 넘어가지 않고 거부합니다	`aside-models.json`	없음 — loopback placeholder
`raycast`	`~/.config/raycast/ai/providers.yaml` (macOS와 Windows 모두 동일. Raycast는 `XDG_CONFIG_HOME`을 따르지 않습니다)	`raycast-providers.yaml`	없음 — loopback 전용. `api_keys` 항목은 쓰지 않습니다
`omo`	`~/.omo/agent/models.json` (`OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PI_CODING_AGENT_DIR` 순서로 설정된 값이 우선. 상대 경로는 거부됩니다)	`omo-models.json`	없음 — loopback placeholder

Raycast 내보내기는 providers 시퀀스에 id: opencodex 요소 하나만 담은 독립 providers.yaml 문서입니다. 내용은 name: OpenCodex, proxy의 /v1 base URL, 그리고 abilities가 붙은 라우팅된 모든 모델입니다(tools와 system_message는 항상 지원, vision은 카탈로그의 입력 모달리티를 따름, reasoning_effort는 모델에 effort 사다리가 있을 때, temperature는 추론 모델에서 꺼짐). Custom Providers는 Raycast Pro 기능이며, Raycast가 이 파일을 감시하므로 저장한 변경은 재시작 없이 적용됩니다. 형식은 manual.raycast.com/ai/custom-providers에 문서화되어 있습니다. api_keys 항목은 쓰지 않으므로 이 내보내기는 loopback 전용이며, loopback이 아닌 bind는 거부됩니다.

opencode는 {env:OPENCODEX_OPENCODE_API_KEY}를 보간합니다. opencodex가 생성한 Pi 블록에는 환경 변수가 필요 없으며, 리터럴 placeholder인 opencodex-loopback이 들어갑니다. 이 값은 필수입니다. Pi는 모델 목록을 만들 때 apiKey를 해석하고, 기존 config에 설정되지 않은 env 참조가 있으면 provider 전체를 숨기기 때문입니다. 루프백에서 proxy는 생성된 placeholder를 검사하지 않습니다.

어떤 key도 직렬화되지 않습니다. 생성되는 config에는 문서화된 env reference 또는 비밀이 아닌 loopback placeholder 중 하나가 들어갑니다. loopback proxy(127.0.0.1, 기본값)는 admission key가 전혀 필요하지 않습니다. proxy가 loopback을 넘어 바인딩할 때는 해당하는 OPENCODEX_OPENCODE_API_KEY, OPENCODEX_HERMES_API_KEY, OPENCODEX_OPENCLAW_API_KEY를 설정하십시오. OPENCODEX_GAJAE_API_KEY는 gjc provider 인증 값을 환경에서 전달하지만 remote admission header를 보낼 수는 없으므로, 생성되는 gjc 통합은 loopback 전용으로 남습니다. admission key가 어떻게 발급되는지는 Remote access를 보십시오. upstream provider 자체의 key는 완전히 별개의 것으로, 각 Providers에 맞게 설정합니다.

같은 payload는 GET /api/client-config로 제공되고 dashboard의 API 탭에도 렌더링되므로, CLI, API, GUI가 모두 같은 바이트를 사용합니다.

런타임과 설정

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

헤드리스 런타임 설정, 시작, 동기화, 진단, 업데이트를 관리합니다.

ocx system codex-restart --yes는 ocx sync --restart-codex와 같은 모듈로 Codex app-server를 재시작하고 데스크톱 앱도 완전히 종료한 뒤 다시 띄웁니다. 프록시 자체가 Codex 앱 안에서 실행 중이면 넘길 수 없는 handoff를 약속하지 않고, 대신 실행 가능한 안내와 함께 거절합니다.

ocx system settings --stream-mode eager-relay

ocx system update는 OpenCodex 자체를 업데이트합니다. Codex CLI는 다음의 별도 읽기 전용 명령으로 점검합니다.

ocx system codex-cli-update check --json

check는 패키지 레지스트리를 조회하지 않고, 설정된 설치 후보에 대해 전체 경로를 숨긴 실행 파일 위치와 소유권 근거를 포함한 provenance 정보를 제한된 범위에서 검사합니다. 신뢰할 수 있는 배포 런처 컨텍스트가 인증하는 것은 후보 스냅샷뿐이며, Codex가 성공적으로 실행되었다는 사실은 인증하지 않습니다. 이 단발성 명령은 Codex를 전혀 실행하지 않으므로 환경 또는 저장된 상태에서 얻은 후보는 보고 전용입니다(managed: false, 일반적으로 selection_unattested). selectionAttested는 항상 false입니다. JSON 출력에는 candidateAvailable, candidateVersion, candidateSource, selectionAttested: false가 포함됩니다. Bun이나 소스에서 직접 실행하면 런처 증거가 없으므로 환경 및 저장된 후보를 무시하고 POSIX에서는 candidate_unavailable을 보고할 수 있습니다. Windows에서는 이 첫 조각이 후보 또는 설정 경로의 파일시스템을 전혀 읽지 않습니다. 배포 런처가 증명한 절대 환경 후보에 한해서 앱 번들 또는 버전 관리자라는 어휘적 표지만 보고하며, 그 밖의 Windows 후보는 모두 실패 닫힘 처리합니다. 이 조각은 저장된 선택 상태를 전혀 읽지 않으므로, 환경 후보가 캡처되지 않은 Windows 실행은 candidate_unavailable이 아니라 windows_inspection_deferred를 보고합니다. 명령이 Codex CLI 설치 여부를 관측할 수 없으므로, 후보가 없다고 단정하는 대신 검사가 연기되었음을 보고합니다. 이 명령은 Codex나 패키지 관리자를 실행하거나 shim을 복구하지 않고, 설정 또는 캐시 상태를 쓰거나 프로세스를 중지하거나 어떤 것도 설치하지 않습니다. 앱에 포함된 후보, 인식된 버전 관리자의 후보, 검증되지 않은 독립 실행형 후보, shim 상태가 모호한 후보는 관리 대상이 아니거나 알 수 없는 것으로 보고되며, 관리 대상으로 분류되지 않습니다.

Windows에서 CODEX_CLI_PATH=codex 같은 단순 명령 이름이나 원격 경로·장치 경로가 후보로 캡처되면 candidate_path_unavailable을 보고합니다. 후보는 캡처됐지만 해당 경로가 이 검사 대상에 적합하지 않은 경우입니다.

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

검증된 OpenCodex configuration을 검사하고 안전하게 수정합니다. show와 get은 비밀 값을 가립니다. import는 쓰기 전에 검증하며 --yes가 필요합니다.

연결된 클라이언트의 사용량

ocx usage는 등록된 데이터 키로 허브에서 이 클라이언트의 사용량만 읽습니다. 출력에는 허브 출처와 키 범위가 표시됩니다. 기간·모델·공급자 필터와 --since/--until, --json을 그대로 사용할 수 있습니다. 계정별 내역과 다른 클라이언트 기록은 반환하지 않습니다. 허브가 응답하지 않거나 이 기능을 지원하지 않으면 오류를 알립니다. 로컬 기록으로 대신 표시하지 않습니다. 구형 허브라면 허브를 업데이트하세요.

CLI 에이전트, 라우팅, 통합

에이전트 정책

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

ocx effort [status|set|clear]

ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>

콤보 라우팅

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

관측성과 디버그

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

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