Skip to content

Commit 7fdb2cb

Browse files
junjun
authored andcommitted
docs-site: split configuration and CLI references into domain subpages, restructure sub-agent guide, dedupe codex guides
1 parent 1e873f4 commit 7fdb2cb

14 files changed

Lines changed: 1756 additions & 1446 deletions

File tree

‎docs-site/astro.config.mjs‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,27 @@ export default defineConfig({
116116
label: "Reference",
117117
translations: { ko: "레퍼런스", "zh-CN": "参考", ru: "Справочник", ja: "リファレンス" },
118118
items: [
119-
{ label: "CLI", translations: { ko: "CLI", "zh-CN": "命令行", ru: "CLI", ja: "CLI" }, slug: "reference/cli" },
120-
{ label: "Configuration", translations: { ko: "설정", "zh-CN": "配置", ru: "Конфигурация", ja: "設定" }, slug: "reference/configuration" },
119+
{
120+
label: "CLI",
121+
translations: { ko: "CLI", "zh-CN": "命令行", ru: "CLI", ja: "CLI" },
122+
items: [
123+
{ label: "Overview", translations: { ko: "개요", "zh-CN": "概览", ru: "Обзор", ja: "概要" }, slug: "reference/cli" },
124+
{ label: "Lifecycle & Service", translations: { ko: "라이프사이클 & 서비스", "zh-CN": "生命周期与服务", ru: "Жизненный цикл и служба", ja: "ライフサイクル & サービス" }, slug: "reference/cli/lifecycle" },
125+
{ label: "Providers, Accounts & Models", translations: { ko: "프로바이더, 계정 & 모델", "zh-CN": "提供商、账户与模型", ru: "Провайдеры, аккаунты и модели", ja: "プロバイダー・アカウント・モデル" }, slug: "reference/cli/providers-accounts" },
126+
{ label: "Agents, Routing & Integrations", translations: { ko: "에이전트, 라우팅 & 통합", "zh-CN": "代理、路由与集成", ru: "Агенты, маршрутизация и интеграции", ja: "エージェント・ルーティング・連携" }, slug: "reference/cli/agents" },
127+
],
128+
},
129+
{
130+
label: "Configuration",
131+
translations: { ko: "설정", "zh-CN": "配置", ru: "Конфигурация", ja: "設定" },
132+
items: [
133+
{ label: "Overview", translations: { ko: "개요", "zh-CN": "概览", ru: "Обзор", ja: "概要" }, slug: "reference/configuration" },
134+
{ label: "Providers", translations: { ko: "프로바이더", "zh-CN": "提供商", ru: "Провайдеры", ja: "プロバイダー" }, slug: "reference/configuration/providers" },
135+
{ label: "Routing", translations: { ko: "라우팅", "zh-CN": "路由", ru: "Маршрутизация", ja: "ルーティング" }, slug: "reference/configuration/routing" },
136+
{ label: "Agents", translations: { ko: "에이전트", "zh-CN": "代理", ru: "Агенты", ja: "エージェント" }, slug: "reference/configuration/agents" },
137+
{ label: "Server & Runtime", translations: { ko: "서버 & 런타임", "zh-CN": "服务器与运行时", ru: "Сервер и рантайм", ja: "サーバー & ランタイム" }, slug: "reference/configuration/server" },
138+
],
139+
},
121140
{ label: "Adapters", translations: { ko: "어댑터", "zh-CN": "适配器", ru: "Адаптеры", ja: "アダプター" }, slug: "reference/adapters" },
122141
{ label: "Architecture", translations: { ko: "아키텍처", "zh-CN": "架构", ru: "Архитектура", ja: "アーキテクチャ" }, slug: "reference/architecture" },
123142
{ label: "Proxy API Formats", translations: { ko: "프록시 API 형식", "zh-CN": "代理 API 格式", ru: "Форматы API прокси", ja: "プロキシAPI形式" }, slug: "reference/proxy-formats" },

‎docs-site/src/content/docs/getting-started/quickstart.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ ocx init
2626
The result is saved to `$OPENCODEX_HOME/config.json` (default `~/.opencodex/config.json`).
2727

2828
:::note[GPT-5.6 rollout entries]
29-
Stable v2.7.1 seeds GPT-5.6 Sol/Terra/Luna for ChatGPT passthrough, OpenAI API-key, OpenRouter, and
29+
The current stable release seeds GPT-5.6 Sol/Terra/Luna for ChatGPT passthrough, OpenAI API-key,
30+
OpenRouter, and
3031
the experimental Cursor adapter. They work only when that upstream account has access. The OpenAI
3132
API-key and OpenRouter presets advertise a 372,000-token usable context window; Cursor keeps its own
3233
adapter metadata.
@@ -76,7 +77,8 @@ codex -m "ollama-cloud/glm-5.2" "Write a SQL migration"
7677
A fresh config features five native models in Codex's sub-agent picker: `gpt-5.5`,
7778
`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4-mini`. Open `ocx gui` to replace or
7879
reorder up to five native or routed models. The dashboard can also set one preferred sub-agent model
79-
and reasoning effort; opencodex adds that guidance to v1 collaboration requests.
80+
and reasoning effort. See [Sub-agent Surface](/guides/sub-agent-surface/) to choose v1/base/v2 and
81+
understand when guidance, native defaults, and fallback apply.
8082

8183
## Logging in instead of pasting a key
8284

‎docs-site/src/content/docs/guides/codex-app-models.md‎

Lines changed: 7 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -35,40 +35,9 @@ Earlier v1 three-provider configurations migrate automatically into the single o
3535

3636
## Integration path
3737

38-
`ocx init`, `ocx start`, and `ocx sync` keep these Codex files aligned under the resolved
39-
`CODEX_HOME` directory:
40-
41-
```text
42-
$CODEX_HOME/config.toml
43-
$CODEX_HOME/opencodex.config.toml
44-
$CODEX_HOME/opencodex-catalog.json
45-
$CODEX_HOME/models_cache.json
46-
```
47-
48-
On the default loopback bind, Codex keeps its built-in `openai` provider id. opencodex installs root
49-
keys that point the provider and model catalog at the proxy:
50-
51-
```toml
52-
model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
53-
openai_base_url = "http://127.0.0.1:10100/v1"
54-
```
55-
56-
For a non-loopback hostname, Codex also needs the generated API-auth header. That mode uses a root
57-
`model_provider = "opencodex"` key and a dedicated Responses-compatible provider:
58-
59-
```toml
60-
[model_providers.opencodex]
61-
name = "OpenCodex Proxy"
62-
base_url = "http://your-host:10100/v1"
63-
wire_api = "responses"
64-
requires_openai_auth = true
65-
env_http_headers = { "x-opencodex-api-key" = "OPENCODEX_API_AUTH_TOKEN" }
66-
```
67-
68-
`websockets` is off by default. Dedicated-provider and catalog entries advertise
69-
`supports_websockets = true` only when `"websockets": true`; on loopback, Codex's built-in provider
70-
may probe WebSocket first, and a disabled proxy returns `426` so Codex falls back to HTTP/SSE. See
71-
[Codex Integration](/guides/codex-integration/) for the full injection and restore flow.
38+
`ocx init`, `ocx start`, and `ocx sync` wire the shared Codex config and catalog into the proxy; see
39+
[Codex Integration](/guides/codex-integration/) for config injection, catalog sync, shims, WebSocket
40+
fallback, and restore mechanics.
7241

7342
## Why routed models show up
7443

@@ -85,7 +54,7 @@ The clone keeps strict-parser fields such as reasoning levels, shell type, API s
8554
base instructions. opencodex then removes native-only capabilities that the route cannot honor,
8655
including OpenAI service-tier metadata.
8756

88-
## Model coverage in v2.7.1
57+
## Current stable model coverage
8958

9059
The native fallback set includes `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
9160
`gpt-5.3-codex-spark`, and GPT-5.6 Sol/Terra/Luna. For the GPT-5.5/5.4 family, opencodex preserves
@@ -124,24 +93,9 @@ forces Codex's model cache stale after a toggle.
12493

12594
## Multi-agent surface mode
12695

127-
opencodex adds a 3-state override for the `multi_agent_version` field on every catalog entry:
128-
129-
| Mode | Effect |
130-
| --- | --- |
131-
| **v1** | Force every model to the v1 multi-agent surface, overriding upstream pins (including Sol/Terra). |
132-
| **base** (install default) | Restore upstream pins: Sol/Terra use v2, Luna uses v1, and unpinned models follow the Codex `multi_agent_v2` feature flag. |
133-
| **v2** | Force every model to the v2 multi-agent surface, overriding upstream pins (including Luna). |
134-
135-
Set the mode from the Dashboard or Models page, `ocx v2 mode v1|default|v2`, or `PUT /api/v2`
136-
with `{ "multiAgentMode": "v1" }`. Changes apply to new Codex sessions.
137-
138-
:::caution
139-
On the v2 (`multi_agent_v2`) surface, a spawn without an explicit model can inherit the parent
140-
session's model. OpenCodex guidance can ask Codex to pass the selected model/effort explicitly, and
141-
the separate native-default opt-in can supply defaults after sync/restart. Neither mechanism is a
142-
proxy-side per-spawn router. See [Sub-agent Surface](/guides/sub-agent-surface/) for the canonical
143-
behavior.
144-
:::
96+
The Models-page v1/base/v2 control changes which Codex collaboration surface each picker entry uses;
97+
see [Sub-agent Surface](/guides/sub-agent-surface/) for the canonical mode, delegation, inheritance,
98+
fallback, and encrypted-task behavior.
14599

146100
## Reasoning top tiers
147101

‎docs-site/src/content/docs/guides/codex-integration.md‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Codex Integration
3-
description: How opencodex injects itself into Codex, syncs the model catalog, drives the subagent picker, and restores cleanly.
3+
description: How opencodex injects itself into Codex, syncs the model catalog, installs shims, and restores cleanly.
44
---
55

66
opencodex makes Codex route through the proxy by editing two things Codex reads: its config
@@ -303,24 +303,7 @@ it is not; `ocx doctor` reports restart safety (service/shim coverage).
303303

304304
## The subagent picker
305305

306-
Codex's `spawn_agent` advertises the first **5 picker-visible catalog models** after sorting by
307-
priority. `subagentModels` accepts up to five ids, either bare native GPT slugs or namespaced
308-
`provider/model` routes, and gives them priorities 0–4 so they sort first:
309-
310-
```json
311-
{
312-
"subagentModels": [
313-
"gpt-5.5",
314-
"gpt-5.6-sol",
315-
"anthropic/claude-opus-5",
316-
"xai/grok-4.5",
317-
"cursor/gpt-5.6-terra"
318-
]
319-
}
320-
```
321-
322-
Priority ranking: featured (0–4) < other routed (5) < native (9). You can also manage this from the
323-
[web dashboard](/guides/web-dashboard/).
306+
Catalog sync makes the selected sub-agent models available to Codex; see [Codex App model picker](/guides/codex-app-models/#subagent-selection) for picker ordering and [Sub-agent Surface](/guides/sub-agent-surface/) for v1/base/v2 delegation and fallback behavior.
324307

325308
## Codex account warmup
326309

0 commit comments

Comments
 (0)