Skip to content

Commit 0c4be13

Browse files
committed
fix(codex): clarify external provider handoff
1 parent 8de2941 commit 0c4be13

4 files changed

Lines changed: 40 additions & 13 deletions

File tree

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

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,10 @@ env_http_headers = { "x-opencodex-api-key" = "OPENCODEX_API_AUTH_TOKEN" }
6666
# supports_websockets = true # only when config.websockets is true
6767
```
6868

69-
In both modes opencodex writes `$CODEX_HOME/opencodex.config.toml` as a reference/fallback config.
70-
On loopback it contains the root keys you can merge manually if automatic injection was removed;
71-
on non-loopback it contains the dedicated provider form.
69+
When OpenCodex owns routing, both modes write `$CODEX_HOME/opencodex.config.toml` as a
70+
reference/fallback config. On loopback it contains the root keys you can merge manually if automatic
71+
injection was removed; on non-loopback it contains the dedicated provider form. External-provider
72+
mode leaves this profile untouched.
7273

7374
:::caution
7475
Root keys such as `openai_base_url`, `model_provider`, and `model_catalog_json` **must** sit before the
@@ -161,9 +162,11 @@ existing sessions with that provider id; replacing the active id can make those
161162
disappear from Codex's history view.
162163

163164
Keep one tool as the owner of Codex provider configuration. To use OpenCodex behind an existing
164-
provider manager, point that manager at the local OpenAI-compatible endpoint
165-
`http://127.0.0.1:10100/v1`. To let OpenCodex inject routing directly, first switch Codex back to its
166-
built-in `openai` provider, then rerun `ocx start`.
165+
provider manager, point that provider at `http://127.0.0.1:10100/v1` with Responses passthrough
166+
(`wire_api = "responses"` in Codex TOML), not Chat Completions translation. When proxy API auth is
167+
enabled, also pass `x-opencodex-api-key` from `OPENCODEX_API_AUTH_TOKEN`, matching the non-loopback
168+
provider form above. To let OpenCodex inject routing directly, first switch Codex back to its
169+
built-in `openai` provider and remove any user-owned root `openai_base_url`, then rerun `ocx start`.
167170

168171
### Catalog troubleshooting
169172

‎src/codex/inject.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -372,7 +372,9 @@ export async function injectCodexConfig(port: number, config?: OcxConfig, option
372372
success: true,
373373
message: `⚠️ Codex routing NOT injected: config.toml selects the external model_provider ${tomlString(activeProvider)}.\n` +
374374
` OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n` +
375-
` Configure your provider manager to use http://${providerBaseHost(config?.hostname)}:${port}/v1, or switch Codex to the built-in openai provider and rerun 'ocx start'.`,
375+
` Configure that provider for Responses passthrough at http://${providerBaseHost(config?.hostname)}:${port}/v1` +
376+
`${shouldInjectApiAuthHeader(config) ? ` with x-opencodex-api-key from OPENCODEX_API_AUTH_TOKEN` : ""}.\n` +
377+
` For direct injection, switch to the built-in openai provider, remove any user-owned root openai_base_url, and rerun 'ocx start'.`,
376378
};
377379
}
378380

‎structure/02_config-and-codex-home.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,16 +38,17 @@ Root TOML keys must be written before the first `[table]`. Re-injection strips s
3838
blocks, stale root context-window overrides, and stale opencodex catalog paths before rewriting.
3939

4040
If the root config selects a provider other than `openai` or `opencodex`, injection must leave the
41-
config byte-for-byte unchanged and skip history migration. External provider managers own that
42-
routing configuration, and replacing their provider id can hide otherwise intact Codex sessions.
41+
config byte-for-byte unchanged and skip profile creation/updates and history migration. External
42+
provider managers own that routing configuration, and replacing their provider id can hide
43+
otherwise intact Codex sessions.
4344

4445
`supports_websockets = true` is appended only when `websocketsEnabled(config)` returns true.
4546

4647
## Profile and fast tier
4748

48-
opencodex also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile target. Codex config
49-
uses `service_tier = "fast"` and `[features].fast_mode = true`; catalog/request tier metadata may use
50-
`priority`. Do not collapse these spellings into one value.
49+
When opencodex owns routing, it also writes `$CODEX_HOME/opencodex.config.toml` as an explicit profile
50+
target. Codex config uses `service_tier = "fast"` and `[features].fast_mode = true`;
51+
catalog/request tier metadata may use `priority`. Do not collapse these spellings into one value.
5152

5253
## Provider output defaults
5354

‎tests/codex-inject-integration.test.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
import { describe, expect, test, beforeEach, afterEach } from "bun:test";
2-
import { existsSync, mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
2+
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
33
import { spawnSync } from "node:child_process";
44
import { tmpdir } from "node:os";
55
import { dirname, join } from "node:path";
66
import { fileURLToPath } from "node:url";
7+
import { Database } from "bun:sqlite";
78

89
const repoRoot = dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
910

@@ -115,6 +116,24 @@ describe("injectCodexConfig integration (Design B)", () => {
115116
].join("\n");
116117
writeFileSync(join(codexHome, "config.toml"), original, "utf8");
117118

119+
const sessionsDir = join(codexHome, "sessions");
120+
mkdirSync(sessionsDir);
121+
const rolloutPath = join(sessionsDir, "rollout-custom.jsonl");
122+
const rollout = JSON.stringify({
123+
type: "session_meta",
124+
payload: { id: "thread-custom", model_provider: "custom", source: "cli", cwd: codexHome },
125+
}) + "\n";
126+
writeFileSync(rolloutPath, rollout, "utf8");
127+
const dbPath = join(codexHome, "state_5.sqlite");
128+
const db = new Database(dbPath);
129+
db.run(`CREATE TABLE threads (
130+
id TEXT PRIMARY KEY, rollout_path TEXT NOT NULL, model_provider TEXT NOT NULL,
131+
source TEXT NOT NULL, first_user_message TEXT NOT NULL, has_user_event INTEGER NOT NULL
132+
)`);
133+
db.run(`INSERT INTO threads VALUES ('thread-custom', ?, 'custom', 'cli', 'hello', 1)`, rolloutPath);
134+
db.close();
135+
const dbBefore = readFileSync(dbPath);
136+
118137
const r = runInject(codexHome, ocxHome);
119138
expect(r.status).toBe(0);
120139
const result = JSON.parse(r.stdout);
@@ -124,6 +143,8 @@ describe("injectCodexConfig integration (Design B)", () => {
124143

125144
expect(readFileSync(join(codexHome, "config.toml"), "utf8")).toBe(original);
126145
expect(existsSync(join(codexHome, "opencodex.config.toml"))).toBe(false);
146+
expect(readFileSync(dbPath).equals(dbBefore)).toBe(true);
147+
expect(readFileSync(rolloutPath, "utf8")).toBe(rollout);
127148
});
128149

129150
test("non-loopback hostname still uses the legacy provider-table injection", () => {

0 commit comments

Comments
 (0)