fix(codex): warn when codex-shim install cannot prove routing (#1169)

docs-site/src/content/docs/reference/cli/lifecycle.md

@@ -287,6 +287,14 @@ dashboard UAC prompt or rerun `ocx service install` in an elevated PowerShell wi
 Wrap a script-based `codex` launcher on PATH with a lightweight autostart script. Real `codex.exe`
 targets are left untouched to avoid breaking exact executable invocations.
 
+Launcher installation alone does not prove that Codex requests will use OpenCodex. After a healthy
+install, the command checks the current Codex routing and reports a warning instead of a green result
+when routing is external, user-owned, or unverifiable. It also warns when outbound proxy variables
+exist only in the current process while `config.proxy` is unset or unresolved, because Codex
+launchers and background services may not inherit that environment. These checks are read-only and
+never print proxy values; resolve the reported handoff and run `ocx doctor` before relying on
+autostart.
+
 If a completed external Codex update overwrites an installed shim, the next ordinary `ocx` command
 backs up the stable new launcher and restores the shim before dispatch. A launcher that is still
 changing is left untouched and retried later. Repair failures warn without failing the requested

docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md

@@ -178,6 +178,8 @@ ocx service uninstall
 
 在 PATH 上把基于脚本的 `codex` 启动器包装为一个轻量自启动脚本。真实的 `codex.exe` 目标会保持不变，以避免破坏精确的可执行文件调用。
 
+仅安装启动器并不能证明 Codex 请求会经过 OpenCodex。完成健康安装后，命令会检查当前 Codex 路由；当路由由外部配置、用户自有网关管理或无法验证时，会显示警告而不是绿色成功。若出站代理变量只存在于当前进程，而 `config.proxy` 未设置或无法解析，也会给出警告，因为 Codex 启动器和后台服务未必继承该环境。这些检查只读且绝不会打印代理值；在依赖自动启动前，请先处理提示的交接配置并运行 `ocx doctor`。
+
 如果已完成的外部 Codex 更新覆盖了已安装的 shim，下一次普通的 `ocx` 命令会先备份稳定的新启动器，再在分发前恢复 shim。仍在变动中的启动器会保持不动，并在稍后重试。修复失败只会警告，不会让所请求的命令失败；手动回退：`ocx codex-shim install`。将 `codexShimAutoRestore` 设为 `false`，或设置 `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`，即可在进程级别关闭自动恢复。
 
 | 子命令 | 操作 |

src/cli/codex-shim-readiness.ts

@@ -0,0 +1,69 @@
+import {
+  currentExternalCodexModelProvider,
+  getCodexRoutingKind,
+  type CodexRoutingKind,
+} from "../codex/inject";
+import { loadConfig, resolveEnvValue } from "../config";
+
+const PROXY_ENV_KEYS = [
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "all_proxy",
+] as const;
+
+export interface CodexShimReadinessInputs {
+  routingKind: CodexRoutingKind;
+  externalProvider: string | null;
+  processProxyEnvPresent: boolean;
+  configuredProxyResolved: boolean;
+}
+
+function externalProviderLabel(provider: string | null): string {
+  return provider
+    ? `external model_provider ${JSON.stringify(provider)}`
+    : "the active Codex route";
+}
+
+export function codexShimReadinessWarnings(
+  inputs: CodexShimReadinessInputs,
+): string[] {
+  const warnings: string[] = [];
+  const provider = externalProviderLabel(inputs.externalProvider);
+
+  if (inputs.routingKind === "unknown") {
+    warnings.push(
+      inputs.externalProvider
+        ? `Codex still selects ${provider}. The shim can start OpenCodex, but it does not redirect that provider; point it at the live OpenCodex /v1 endpoint with wire_api = "responses", or switch to the built-in openai provider and run 'ocx sync'.`
+        : "Codex routing could not be verified. The shim can start OpenCodex, but it may not redirect Codex; run 'ocx doctor' before relying on autostart.",
+    );
+  } else if (inputs.routingKind === "custom-local") {
+    warnings.push(
+      `Codex uses ${provider} through a user-owned local gateway. The shim can start OpenCodex, but OpenCodex does not own that route; run 'ocx doctor' to verify its lifecycle.`,
+    );
+  } else if (inputs.routingKind === "custom-remote") {
+    warnings.push(
+      `Codex uses ${provider} through a remote gateway. The shim only starts a local OpenCodex proxy and will not affect those requests.`,
+    );
+  }
+
+  if (inputs.processProxyEnvPresent && !inputs.configuredProxyResolved) {
+    warnings.push(
+      "Proxy environment variables are present only in this process while config.proxy is unset or unresolved. Codex launchers and background services may not inherit them; persist config.proxy before relying on autostart.",
+    );
+  }
+
+  return warnings;
+}
+
+export function collectCodexShimReadinessWarnings(): string[] {
+  const config = loadConfig();
+  return codexShimReadinessWarnings({
+    routingKind: getCodexRoutingKind(),
+    externalProvider: currentExternalCodexModelProvider(),
+    processProxyEnvPresent: PROXY_ENV_KEYS.some(key => Boolean(process.env[key]?.trim())),
+    configuredProxyResolved: Boolean(resolveEnvValue(config.proxy)?.trim()),
+  });
+}

src/cli/index.ts

@@ -1160,11 +1160,16 @@ switch (command) {
     break;
   }
   case "codex-shim": {
-    const { codexShimStatus, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
+    const { codexShimStatus, diagnoseCodexShim, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
     switch (args[1]) {
       case "install": {
         const r = installCodexShim();
-        console.log(r.installed ? `✅ ${r.message}` : `⚠️  ${r.message}`);
+        const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
+        const warnings = diagnoseCodexShim().healthy
+          ? collectCodexShimReadinessWarnings()
+          : [];
+        console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
+        for (const warning of warnings) console.warn(`   ${warning}`);
         break;
       }
       case "status":

tests/codex-shim-readiness.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { codexShimReadinessWarnings } from "../src/cli/codex-shim-readiness";
+
+const repoRoot = dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+const cliPath = join(repoRoot, "src", "cli", "index.ts");
+
+const ready = {
+  routingKind: "native" as const,
+  externalProvider: null,
+  processProxyEnvPresent: false,
+  configuredProxyResolved: false,
+};
+
+describe("Codex shim install readiness", () => {
+  test("keeps a clean install green for native and managed routing", () => {
+    expect(codexShimReadinessWarnings(ready)).toEqual([]);
+    expect(codexShimReadinessWarnings({
+      ...ready,
+      routingKind: "opencodex-local",
+    })).toEqual([]);
+  });
+
+  test("warns when an external provider is not routed through OpenCodex", () => {
+    const warnings = codexShimReadinessWarnings({
+      ...ready,
+      routingKind: "unknown",
+      externalProvider: "custom",
+    });
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('external model_provider "custom"');
+    expect(warnings[0]).toContain("live OpenCodex /v1 endpoint");
+    expect(warnings[0]).toContain('wire_api = "responses"');
+
+  });
+
+  test("distinguishes user-owned local and remote routes", () => {
+    const local = codexShimReadinessWarnings({
+      ...ready,
+      routingKind: "custom-local",
+      externalProvider: "gateway",
+    });
+    expect(local).toHaveLength(1);
+    expect(local[0]).toContain("user-owned local gateway");
+    expect(local[0]).toContain("ocx doctor");
+
+    const remote = codexShimReadinessWarnings({
+      ...ready,
+      routingKind: "custom-remote",
+      externalProvider: "gateway",
+    });
+    expect(remote).toHaveLength(1);
+    expect(remote[0]).toContain("remote gateway");
+    expect(remote[0]).toContain("will not affect those requests");
+  });
+
+  test("warns about process-only proxy settings without exposing a URL", () => {
+    const warnings = codexShimReadinessWarnings({
+      ...ready,
+      processProxyEnvPresent: true,
+      configuredProxyResolved: false,
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("config.proxy");
+    expect(warnings[0]).toContain("may not inherit");
+    expect(warnings[0]).not.toContain("://");
+
+    expect(codexShimReadinessWarnings({
+      ...ready,
+      processProxyEnvPresent: true,
+      configuredProxyResolved: true,
+    })).toEqual([]);
+  });
+
+  test("the install command surfaces readiness warnings without leaking the proxy URL", () => {
+    if (process.platform === "win32") return;
+
+    const root = mkdtempSync(join(tmpdir(), "ocx-shim-readiness-"));
+    const codexHome = join(root, "codex-home");
+    const opencodexHome = join(root, "opencodex-home");
+    const binDir = join(root, "bin");
+    mkdirSync(codexHome);
+    mkdirSync(opencodexHome);
+    mkdirSync(binDir);
+    try {
+      writeFileSync(join(codexHome, "config.toml"), [
+        'model_provider = "custom"',
+        "",
+        "[model_providers.custom]",
+        'name = "OpenAI"',
+        'wire_api = "responses"',
+        "",
+      ].join("\n"), "utf8");
+      writeFileSync(join(opencodexHome, "config.json"), `${JSON.stringify({
+        port: 10100,
+        providers: {
+          openai: {
+            adapter: "openai-responses",
+            baseUrl: "https://chatgpt.com/backend-api/codex",
+            authMode: "forward",
+          },
+        },
+        defaultProvider: "openai",
+      }, null, 2)}\n`, "utf8");
+      const codex = join(binDir, "codex");
+      writeFileSync(codex, "#!/bin/sh\nexit 0\n", "utf8");
+      chmodSync(codex, 0o755);
+
+      const proxyUrl = "http://user:secret@127.0.0.1:7890";
+      const result = spawnSync(process.execPath, [cliPath, "codex-shim", "install"], {
+        cwd: repoRoot,
+        env: {
+          ...process.env,
+          CODEX_HOME: codexHome,
+          OPENCODEX_HOME: opencodexHome,
+          PATH: `${binDir}:${process.env.PATH ?? ""}`,
+          HTTP_PROXY: proxyUrl,
+          HTTPS_PROXY: proxyUrl,
+        },
+        encoding: "utf8",
+      });
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toStartWith("⚠️  Codex autostart shim installed");
+      expect(result.stderr).toContain('external model_provider "custom"');
+      expect(result.stderr).toContain("config.proxy");
+      expect(`${result.stdout}\n${result.stderr}`).not.toContain(proxyUrl);
+      expect(`${result.stdout}\n${result.stderr}`).not.toContain("user:secret");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});