自学教程

Codex 非交互模式与跨平台

Codex 教程

Codex 非交互模式支持跨平台运行，可在 Windows、Linux、macOS 环境执行无头自动化任务。跨平台特性让同一份 Codex 项目配置、任务脚本、MCP服务、规则钩子能够在多操作系统复用，是 CI/CD、多机器开发流水线、跨环境批量代码处理的基础。本文讲解跨平台支持范围、平台差异、配置适配、跨平台脚本编写、容器部署与兼容性排错。

一、跨平台支持概述

Codex 非交互模式核心程序原生支持三大操作系统：Linux、macOS、Windows。
同一份项目仓库（.codex/ 目录下全部配置）提交Git后，在不同操作系统拉取，加载相同规则、MCP服务、Agent Skills、子代理、钩子，无需大幅修改。

核心前提：非交互模式为无头执行，不依赖图形界面，因此天然适合跨服务器、容器、云主机环境。Computer Use 图形操控功能在非交互跨平台环境不可用。

平台支持状态运行方式典型场景
Linux✅ 完全支持二进制 / 容器CI服务器、云主机、流水线
macOS✅ 完全支持二进制本地开发工作站
Windows✅ 支持exe / PowerShellWindows服务器、本地Windows开发机

二、跨平台关键差异点

虽然 Codex 配置文件（toml/md/json）跨平台通用，但底层系统环境存在差异，编写自动化任务时需要重点注意。

2.1 路径分隔符

  • Linux/macOS：/ 正斜杠
  • Windows：\ 反斜杠
    Codex 内部配置解析器自动兼容两种分隔符，在 .codex/config.toml、rules.toml 中统一推荐使用正斜杠写法，跨平台不会报错。
    示例（全平台通用写法）
[file_protection]
protected = ["config/.env", "src/app.ts"]

2.2 可执行程序与命令差异

这是跨平台脚本最大的坑：

  1. Linux/macOS 使用 bash，Windows 使用 powershell / cmd。
  2. 程序名称不同：例如 ls（Linux/macOS）与 dir（Windows）。

建议：钩子脚本、codex exec 任务描述内，尽量避免直接写平台专属shell命令；优先调用MCP服务完成文件查询，减少直接执行系统命令。

2.3 全局配置文件路径

全局用户配置不属于项目仓库，路径随操作系统变化：

  • Linux / macOS：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

项目级配置 .codex/config.toml 放在代码仓库，全平台路径完全一致，优先使用项目配置，减少全局配置依赖。

2.4 环境变量写法

  • Linux/macOS：${VAR_NAME}
  • Windows PowerShell：$env:VAR_NAME
    Codex配置文件内部 ${VAR_NAME} 语法统一支持全平台，在toml配置中引用环境变量不需要修改写法。

三、跨平台非交互模式基础命令

命令行语法 codex exec 在三大平台保持一致，仅终端环境不同。

Linux/macOS 示例

codex exec --quiet --approval-mode=suggest "评审当前代码变更"

Windows PowerShell 示例

codex exec --quiet --approval-mode=suggest "评审当前代码变更"

管道输入跨平台注意：

  • Linux/macOS：git diff | codex exec "评审变更"
  • Windows PowerShell：git diff | codex exec "评审变更"（PowerShell原生支持管道）

推荐：任务描述、参数、--json、--output 等参数全部跨平台一致，不需要修改。

四、跨平台钩子脚本适配

钩子（Hooks）是跨平台最容易出问题的模块，因为钩子会直接调用本机脚本。

方案1：多平台分支钩子（推荐）

在 config.toml 中使用平台判断，为不同操作系统绑定不同脚本。

[hooks]
pre-task.linux = "./.codex/hooks/pre-task-linux.sh"
pre-task.macos = "./.codex/hooks/pre-task-macos.sh"
pre-task.windows = "powershell ./.codex/hooks/pre-task-win.ps1"

方案2：跨平台统一脚本

使用 Python / Node.js 编写钩子脚本，脚本语言本身跨平台，一份脚本三大系统运行，不需要区分shell。

[hooks]
post-task = "python ./.codex/hooks/post_check.py"

最佳实践：钩子逻辑尽量用跨平台编程语言实现，减少bash/powershell平台专属脚本。

五、容器化跨平台部署（Docker）

容器是保证跨平台一致性的首选方案，在Docker容器内运行Codex非交互模式，屏蔽宿主机系统差异。

基础Dockerfile片段

FROM ubuntu:24.04
RUN apt update && apt install -y ca-certificates
# 安装 codex 二进制
COPY codex /usr/local/bin/codex
WORKDIR /workspace
# 启动非交互任务
CMD ["codex", "exec", "--quiet", "执行项目代码检查"]

容器优势：

  • 环境固定，不受宿主机Linux发行版、Windows/macOS差异影响
  • 可直接嵌入CI流水线，多平台CI均可复用同一个镜像
  • 沙箱隔离，适合full-auto自动执行场景

六、跨平台MCP服务配置

MCP配置在 config.toml 中跨平台通用，但 stdio 模式下启动命令需要注意：

# 跨平台MCP示例，优先使用npx/uvx这类跨平台包管理器
[mcp_servers.git]
name = "git"
transport = "stdio"
command = "uvx"
args = ["mcp-server-git"]
sandbox_mode = "read-only"

避坑：不要硬编码绝对路径（如 /usr/bin/python 或 C:\python.exe），优先使用PATH内可执行程序，保证跨平台查找。

七、跨平台校验命令

Codex内置斜杆命令，在非交互模式下可用来检测当前平台环境，用于自动化脚本校验：

# 查看当前平台信息
codex env info --platform# 验证当前项目配置兼容性（跨平台检查）
codex config validate --cross-platform

输出会提示：路径、钩子脚本、MCP命令是否存在平台兼容性风险。

八、安全与最佳实践

  1. 项目配置全部相对路径，不要写绝对路径，保证仓库在Windows/Linux/macOS直接拉取可用。
  2. 钩子优先采用Python/Node.js跨平台脚本，尽量减少bash与powershell专属脚本。
  3. MCP服务使用包管理器（uvx/npx）启动，避免硬编码程序绝对路径。
  4. CI流水线优先使用Docker容器，消除宿主机环境差异带来的不稳定。
  5. 环境变量统一使用 ${VAR_NAME} 写法，不要使用平台特有的变量语法。
  6. 跨平台自动化任务，审批策略默认使用 suggest，仅隔离容器环境启用 auto-edit。
  7. 提交代码前，执行 codex config validate --cross-platform 检查兼容性问题。

九、常见问题

Q：Windows上非交互模式能否加载AGENTS.md、rules.toml和MCP配置？
A：可以。.codex目录下所有配置文件解析逻辑三大平台完全一致。

Q：同一个钩子脚本，Linux正常，Windows执行失败是什么原因？
A：大概率是脚本换行符、shell解释器、可执行权限问题。Windows不支持直接运行sh脚本，建议使用powershell脚本或者python跨平台脚本。

Q：跨平台非交互模式下子代理是否可用？
A：子代理、Agent Skills、MCP全部支持跨平台无头运行，行为在各平台保持一致。

Q：在Windows上使用stdio类型MCP服务有什么限制？
A：stdio模式在Windows支持良好，但部分原生Linux工具无法直接运行，优先选择跨平台的MCP服务。

十、总结

Codex非交互模式具备完整跨平台能力，支持Linux、macOS、Windows三大操作系统。项目内 .codex 的toml、md配置文件跨平台通用，主要差异集中在系统命令、钩子脚本、全局配置路径。

编写跨平台自动化任务时，尽量使用相对路径、跨平台脚本、容器化部署，减少操作系统专属命令。结合codex config validate --cross-platform提前校验兼容性，可实现一套项目配置，在本地工作站、服务器、CI流水线多环境复用。

标签：

0 条笔记