从分发包装器到 Rust Router

阅读契约： 跟着一次 codex invocation 从 package entry point 进入 Rust command router。追踪哪一层可以决定 delivery，哪一层可以暴露 helper aliases，哪一层拥有 product intent。读完本章后，你应该能解释为什么 JavaScript wrapper 有意保持 behavior-poor，而 Rust router 有意保持 typed。

源码边界： 本章的 direct source facts 固定到 OpenAI Codex commit 569ff6a1c400bd514ff79f5f1050a684dc3afde3。被链接的 named files、constants、structs、enum variants、functions 和 branch behavior 属于 verified source。更高层的“delivery contract”、“product owner”、“helper alias”和“startup invariant”是从这些公开锚点得出的 surrounding contract inference，不是关于 OpenAI 私有服务内部的断言。

Codex 用户触碰到的第一个架构边界，不是模型请求，而是 package manager 安装的 command。这个 command 必须跨 operating systems、CPU architectures、optional native packages、vendored artifacts、helper executables、terminal signals 和 shell exit semantics 工作。一个大型 CLI 很容易让 bootstrap script 长成第二个 product router。

Codex 选择更窄的做法。npm package 把 codex 暴露为 bin/codex.js，这个 JavaScript 文件找到并启动 native binary。Rust 启动后，arg0_dispatch_or_else 在 MultitoolCli::parse 把剩余 invocation 变成 typed command 之前处理 helper aliases。这个切分在代码上很小，在设计上很大：packaging 可以决定 binary 在哪里；Rust 决定 Codex 意味着什么。

一、Delivery Contract

Package entry point 只允许回答一个实际问题：给定这个 host 和 installation layout，应该运行哪一个 native executable？它不允许决定 configuration semantics、authentication behavior、remote mode、sandbox policy、thread state 或 tool authority。

这个 contract 从 package manifest 开始：

"bin": {
  "codex": "bin/codex.js"
}

Manifest 没有暴露一组 JavaScript commands。它只暴露一个 installed command。压力在于 package channels 很宽，而 runtime semantics 应该保持窄。

这就是为什么 wrapper 应该被读成 boot boundary，而不是 agent runtime 的开端。Wrapper 准备 native child；它不变成 child。

二、JavaScript Wrapper

2.1 Platform Target 是 Delivery Data

Wrapper 从 Rust target triples 到 platform packages 的有限 map 开始：

const PLATFORM_PACKAGE_BY_TARGET = {
  "x86_64-unknown-linux-musl": "@openai/codex-linux-x64",
  "aarch64-unknown-linux-musl": "@openai/codex-linux-arm64",
  "x86_64-apple-darwin": "@openai/codex-darwin-x64",
  "aarch64-apple-darwin": "@openai/codex-darwin-arm64",
  "x86_64-pc-windows-msvc": "@openai/codex-win32-x64",
  "aarch64-pc-windows-msvc": "@openai/codex-win32-arm64",
};

Map 之后是 process.platform 与 process.arch switch，它要么选择一个已知 target triple，要么抛出 unsupported-platform error。产品重点不是“Codex 以 JavaScript 为先”。事实相反：JavaScript 把 package-manager reality 翻译成一个 native target，然后停止做 product decisions。

2.2 Binary Discovery 有两种 Layout

Native package 可能作为 optional dependency 到达，也可能位于本地 vendor 目录下。Wrapper 让这个选择可见：

let vendorRoot;
try {
  const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
  vendorRoot = path.join(path.dirname(packageJsonPath), "vendor");
} catch {
  if (existsSync(localBinaryPath)) {
    vendorRoot = localVendorRoot;
  } else {
    const packageManager = detectPackageManager();
    const updateCommand =
      packageManager === "bun"
        ? "bun install -g @openai/codex@latest"
        : "npm install -g @openai/codex@latest";
    throw new Error(
      `Missing optional dependency ${platformPackage}. Reinstall Codex: ${updateCommand}`,
    );
  }
}

这段代码故意普通。它不读取 config.toml，不检查 account state，也不根据 command intent 分支。它只发现 vendorRoot，然后用 archRoot、codex 和 platform-specific binary name 形成 binaryPath。Optional dependency 失败会变成 install diagnostic，而不是半个 runtime。

2.3 Spawn 保留 Native Child

Handoff point 是这个文件里最重要的 wrapper code：

const additionalDirs = [];
const pathDir = path.join(archRoot, "path");
if (existsSync(pathDir)) {
  additionalDirs.push(pathDir);
}
const updatedPath = getUpdatedPath(additionalDirs);

const env = { ...process.env, PATH: updatedPath };
const packageManagerEnvVar =
  detectPackageManager() === "bun"
    ? "CODEX_MANAGED_BY_BUN"
    : "CODEX_MANAGED_BY_NPM";
env[packageManagerEnvVar] = "1";

const child = spawn(binaryPath, process.argv.slice(2), {
  stdio: "inherit",
  env,
});

process.argv.slice(2) 是 product-intent clue。Wrapper 转发用户 arguments，而不是解释它们。它把 helper directories 和 package manager markers 加入 environment，然后让 native binary 解析 command。

Wrapper 还保持 shell behavior faithful：

const forwardSignal = (signal) => {
  if (child.killed) {
    return;
  }
  try {
    child.kill(signal);
  } catch {
    /* ignore */
  }
};

["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
  process.on(sig, () => forwardSignal(sig));
});

Child 退出时，parent mirror 终止来自 signal 还是 exit code。这对 scripts 和 terminals 很重要，但仍然不会把 JavaScript 变成 runtime owner。它保留 native process 作为 observable authority。

三、Arg0 Helper Dispatch

Native binary 启动后，Codex 还有一个 pre-router job：按 invocation name 和受控 first argument 做 helper dispatch。arg0 module 在注释里直接说明原因：Codex 想部署一个 CLI binary，同时在 Unix-like systems 上把某些功能暴露为 distinct helper CLIs。

这不是第二个 product router。它是 helper boundary，用于后续 subsystem 需要稳定 executable name 的场景，例如 apply_patch 或 sandbox helper。

把 arg0 读成 executable identity 最后一次允许改变 control flow 的地方。如果 process 被作为 helper 调用，helper branch 会在 product parsing 前评估。如果它作为普通 codex 被调用，alias machinery 只准备后续 children 可以找到的名字。

3.1 Direct Helpers 在普通 Parsing 前停止

第一个 branch 检查 executable 是怎样被调用的：

pub fn arg0_dispatch() -> Option<Arg0PathEntryGuard> {
    // Determine if we were invoked via the special alias.
    let mut args = std::env::args_os();
    let argv0 = args.next().unwrap_or_default();
    let exe_name = Path::new(&argv0)
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("");

    #[cfg(unix)]
    if exe_name == EXECVE_WRAPPER_ARG0 {
        let mut args = std::env::args();
        let _ = args.next();
        let file = match args.next() {
            Some(file) => file,
            None => std::process::exit(1),
        };
        let argv = args.collect::<Vec<_>>();

这个 pattern 有意 pre-parser。它检查 executable name，剥离 helper-specific arguments，并在 ordinary command tree 看见 invocation 前把 control 交给 helper code。

同一个 function 后面还识别 Linux sandbox name、apply_patch、misspelled compatibility name applypatch，以及 first-argument helper modes：

if exe_name == CODEX_LINUX_SANDBOX_ARG0 {
    // Safety: [`run_main`] never returns.
    codex_linux_sandbox::run_main();
} else if exe_name == APPLY_PATCH_ARG0 || exe_name == MISSPELLED_APPLY_PATCH_ARG0 {
    codex_apply_patch::main();
}

let argv1 = args.next().unwrap_or_default();
if argv1 == CODEX_FS_HELPER_ARG1 {
    codex_exec_server::run_fs_helper_main();
}

这些 branches 有意很早。Helper invocation 不应该 fall through 到 codex exec、codex login 或 app-server parsing。Helper name 本身已经是 contract。

3.2 普通 Startup 创建临时 Aliases

如果没有 direct helper 消耗 process，startup 会为 child re-execs 准备 helper aliases。源码明确说明 path entry 为什么存在：

/// This temporary directory is prepended to the PATH environment variable so
/// that `apply_patch` can be on the PATH without requiring the user to
/// install a separate `apply_patch` executable, simplifying the deployment of
/// Codex CLI.
/// Note: In debug builds the temp-dir guard is disabled to ease local testing.
///
/// IMPORTANT: This function modifies the PATH environment variable, so it MUST
/// be called before multiple threads are spawned.
pub fn prepend_path_entry_for_codex_aliases() -> std::io::Result<Arg0PathEntryGuard> {

注释携带两个 startup invariants。Alias availability 只在当前 process lifetime 内有效，PATH 必须在 Codex 启动可能引入多线程的 work 前被修改。

在 Unix 上，这个 function 把 selected helper names symlink 到当前 executable：

for filename in &[
    APPLY_PATCH_ARG0,
    MISSPELLED_APPLY_PATCH_ARG0,
    #[cfg(target_os = "linux")]
    CODEX_LINUX_SANDBOX_ARG0,
    #[cfg(unix)]
    EXECVE_WRAPPER_ARG0,
] {
    let exe = std::env::current_exe()?;

    #[cfg(unix)]
    {
        let link = path.join(filename);
        symlink(&exe, &link)?;
    }

然后它把临时目录 prepend 到 PATH，并通过 Arg0DispatchPaths 返回 stable helper paths：

unsafe {
    std::env::set_var("PATH", updated_path_env_var);
}

let paths = Arg0DispatchPaths {
    codex_self_exe: std::env::current_exe().ok(),
    codex_linux_sandbox_exe: {
        #[cfg(target_os = "linux")]
        {
            Some(path.join(CODEX_LINUX_SANDBOX_ARG0))
        }
        #[cfg(not(target_os = "linux"))]
        {
            None
        }
    },
    main_execve_wrapper_exe: {
        #[cfg(unix)]
        {
            Some(path.join(EXECVE_WRAPPER_ARG0))
        }

临时目录不是 loose side effect。Arg0PathEntryGuard 持有 tempdir 和 lock，生命周期覆盖 process；run_main_with_arg0_guard 只有在 async main function 完成后才 drop 这个 guard。这就是 startup invariant：helper names 在 runtime 可能需要它们时可用，但不永久安装第二套 executable family。

四、Rust Command Router

到这里，distribution 和 helper identity 已经被解决。剩下的是作为 arguments 的 user intent。Rust router 的工作，是把 argument vector 变成一个 typed surface，只把 root-level facts 携带到能够 honor 它们的 surface。

4.1 Root Flags 被收集一次

Helper dispatch 后，main 调用 cli_main，cli_main 解析一个 root command。Parser shape 是 Rust 中第一个 product surface：

/// Codex CLI
///
/// If no subcommand is specified, options will be forwarded to the interactive CLI.
#[derive(Debug, Parser)]
#[clap(
    author,
    version,
    // If a sub-command is given, ignore requirements of the default args.
    subcommand_negates_reqs = true,
    // The executable is sometimes invoked via a platform-specific name like
    // `codex-x86_64-unknown-linux-musl`, but the help output should always use
    // the generic `codex` command name that users run.
    bin_name = "codex",
    override_usage = "codex [OPTIONS] [PROMPT]\n       codex [OPTIONS] <COMMAND> [ARGS]"
)]
struct MultitoolCli {
    #[clap(flatten)]
    pub config_overrides: CliConfigOverrides,

    #[clap(flatten)]
    pub feature_toggles: FeatureToggles,

Root config overrides 和 feature toggles 在 selected subcommand 运行前被收集。这不意味着 wrapper 拥有 configuration。它意味着 Rust parser 有一个地方接收 root-level startup facts，然后把它们传给 selected product surface。

4.2 Subcommands 是 Public Surface Map

Subcommand enum 是 Codex command surfaces 的可读地图。有些 variants 是普通 user-facing entries：

#[derive(Debug, clap::Subcommand)]
enum Subcommand {
    /// Run Codex non-interactively.
    #[clap(visible_alias = "e")]
    Exec(ExecCli),

    /// Run a code review non-interactively.
    Review(ReviewArgs),

    /// Manage login.
    Login(LoginCommand),

    /// Remove stored authentication credentials.
    Logout(LogoutCommand),

    /// Manage external MCP servers for Codex.
    Mcp(McpCli),

其他 variants 暴露 app-server、desktop app、completion、update、sandbox、debug、resume、fork、cloud tasks、exec-server 和 feature inspection。重要设计点不是每个 command 都简单，而是 command intent 在 behavior 运行前表示为 typed Rust variants。

4.3 Dispatch 收窄到一个 Owner

Main dispatch 先解析 root command，并把 feature toggles fold 进 config overrides：

async fn cli_main(arg0_paths: Arg0DispatchPaths) -> anyhow::Result<()> {
    let MultitoolCli {
        config_overrides: mut root_config_overrides,
        feature_toggles,
        remote,
        mut interactive,
        subcommand,
    } = MultitoolCli::parse();

    // Fold --enable/--disable into config overrides so they flow to all subcommands.
    let toggle_overrides = feature_toggles.to_overrides()?;
    root_config_overrides.raw_overrides.extend(toggle_overrides);
    let root_remote = remote.remote;
    let root_remote_auth_token_env = remote.remote_auth_token_env;

    match subcommand {

然后每个 branch 选择一个具体 owner。没有 subcommand 时，TUI 运行。对于 exec，Codex 会拒绝该 subcommand 不支持的 remote-only root flags，继承 shared exec options，prepend root config flags，并调用 codex_exec：

Some(Subcommand::Exec(mut exec_cli)) => {
    reject_remote_mode_for_subcommand(
        root_remote.as_deref(),
        root_remote_auth_token_env.as_deref(),
        "exec",
    )?;
    exec_cli
        .shared
        .inherit_exec_root_options(&interactive.shared);
    prepend_config_flags(
        &mut exec_cli.config_overrides,
        root_config_overrides.clone(),
    );
    codex_exec::run_main(exec_cli, arg0_paths.clone()).await?;
}

这个 branch 很好地体现了 router discipline。它可以把 root facts 适配给一个 surface，但仍然把 work 交给该 surface 的 crate，而不是 inline 实现 headless execution。

App-server 也遵循同样模式，只是 owner 不同：

Some(Subcommand::AppServer(app_server_cli)) => {
    let AppServerCommand {
        subcommand,
        listen,
        analytics_default_enabled,
        auth,
    } = app_server_cli;
    reject_remote_mode_for_app_server_subcommand(
        root_remote.as_deref(),
        root_remote_auth_token_env.as_deref(),
        subcommand.as_ref(),
    )?;
    match subcommand {
        None => {
            let transport = listen;
            let auth = auth.try_into_settings()?;
            codex_app_server::run_main_with_transport(

Router 很宽，因为 command surface 很宽。它仍然是 router，因为每个 branch 选择一个 downstream owner，而不是 inline 执行每个 surface。

五、Visible 和 Hidden Contracts

Hidden commands 很容易被误读。它们是从普通 help output 中隐藏，而不是非正式 shell hacks。源码对 hidden variants 使用同一套 Clap machinery：

/// Execpolicy tooling.
#[clap(hide = true)]
Execpolicy(ExecpolicyCommand),

同一个 enum 还包含 hidden internal relay surfaces：

/// Internal: run the responses API proxy.
#[clap(hide = true)]
ResponsesApiProxy(ResponsesApiProxyArgs),

/// Internal: relay stdio to a Unix domain socket.
#[clap(hide = true, name = "stdio-to-uds")]
StdioToUds(StdioToUdsCommand),

App-server 有自己的 hidden schema-generation variant：

/// [internal] Generate internal JSON Schema artifacts for Codex tooling.
#[clap(hide = true)]
GenerateInternalJsonSchema(GenerateInternalJsonSchemaCommand),

这个区别保护 maintainability。Internal helpers 可以从 casual users 面前隐藏，同时仍然像普通 Rust commands 一样被 parsed、reviewed、tested 和 routed。如果同样行为存在于 ad hoc environment variables 或 unstructured shell snippets 中，release tooling 和后来的读者会少一个可推理 surface。

Remote-mode rejection helpers 展示同一条纪律。源码没有让 --remote 静默泄漏到每个 subcommand：

fn reject_remote_mode_for_subcommand(
    remote: Option<&str>,
    remote_auth_token_env: Option<&str>,
    subcommand: &str,
) -> anyhow::Result<()> {
    if let Some(remote) = remote {
        anyhow::bail!(
            "`--remote {remote}` is only supported for interactive TUI commands, not `codex {subcommand}`"
        );
    }
    if remote_auth_token_env.is_some() {
        anyhow::bail!(
            "`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex {subcommand}`"
        );
    }
    Ok(())
}

没有 negative checks 的 broad router 会变成 permissive router。Codex 使用 typed variants 加 explicit rejection，防止 root-level affordances 意外变成 global behavior。

六、这个边界保护什么

按执行顺序看，startup 有四项工作：把 installed command 解析到 native executable，在 executable 需要 stable names 时暴露 helper aliases，解析一次 root flags 和 subcommands，并拒绝某个 surface 无法 honor 的 root modes。它不构建 session、不选择 model、不决定 approvals、不执行 tools，也不拥有 app-server protocol behavior。它逐步收窄 invocation，直到选中一个 typed owner。

三个常见误读值得提前切断。

第一，“wrapper 找到了 binary”不等于“wrapper 拥有 startup semantics”。它拥有 target selection、binary discovery、PATH adjustment、package-manager markers、spawn 和 signal mirroring。它转发 process.argv.slice(2) 的瞬间，product intent 已经离开 JavaScript。

第二，“arg0 dispatch 发生在 Clap 之前”不等于“有两个 public CLIs”。arg0 处理 helper aliases 和 first-argument helper modes，这些必须在 ordinary parsing 前停止。普通 user intent 仍然流入 MultitoolCli。

第三，“hidden command”不等于“没有 contract 的 private behavior”。Hidden variants 是 source-visible typed commands。它们从 help output 隐藏，是因为服务 internal 或 specialized workflows，而不是因为绕过 router。

七、应用到实践

1. 让 package wrappers 保持 behavior-poor。 它们可以选择 artifacts、准备 helper paths、保留 signals，并启动 native binary；product semantics 留在拥有 runtime 的实现语言里。
2. 把 helper aliases 当成 contracts，而不是 shortcuts。 如果一个 binary 必须呈现多个 helper names，让 dispatch deterministic，并显式保持它的 lifetime。
3. 只解析一次 product intent。 Root flags、feature toggles 和 subcommands 应该进入一个 typed router，而不是被每个 surface 重新解释。
4. 尽早拒绝 unsupported root modes。 一个 shared flag 只有在 surface 能 honor 时才应该被允许；否则在 downstream crate 开始 work 前失败。
5. 即使 hidden，也让 internal commands typed。 隐藏 help output 没问题；隐藏结构不行。Internal tools 仍应有 named variants、arguments 和 source-visible dispatch。

八、结语

当 Codex 到达 product surface 时，startup 已经完成了收窄工作。JavaScript 解决 delivery。arg0 暴露 helper aliases，但没有创建第二套 product CLI。Rust 解析一个 command tree 并选择一个 owner。第 3 章继续追踪这个 owner 下一步需要什么：configuration 和 authentication facts，它们必须在 runtime work 可以安全开始前被解析。