Codex：Rust 编写的开发者智能代理运行时

1. Codex 是什么：别被“类 Claude CLI”标签带偏了方向

Codex 这个名字，最近在开发者圈子里确实火得有点突然。你搜“codex cli”“rust codex”“agents.md”，出来的结果里夹杂着大量和 Claude、DeepSeek、甚至 Copilot 相关的关键词，很容易让人误以为它是个“Claude 的命令行马甲”或者“OpenAI Codex 的开源复刻”。我一开始也这么想，直到亲手在 Ubuntu 20.04 上从零编译、配置、跑通第一个skills，才彻底推翻这个认知——Codex 不是任何大模型的附属品，它是一个以 Rust 编写的、面向开发者工作流的智能代理运行时（Agent Runtime）。

它的核心定位，不是替代你写代码，而是帮你把“重复性高、规则明确、但需要调用多个工具链”的开发任务，封装成可复用、可组合、可调试的“技能单元”。比如，你每天要手动执行git status→git add .→git commit -m "feat: xxx"→git push origin main，这四步操作，在 Codex 里就是一个git-commit-pushskill；再比如，你每次上线前都要跑cargo test+cargo clippy+cargo fmt --check，这三件事也能打包成一个ci-checkskill。Codex 做的，就是把这类“人肉脚本”升级为结构化、可版本管理、可共享的skills。

为什么它必须用 Rust？这不是为了赶时髦。我试过用 Python 写类似的 CLI 工具，启动慢、内存占用高、跨平台分发麻烦（得打包 Python 解释器），而 Codex 的二进制文件编译出来只有 8MB 左右，codex --version响应时间不到 15ms，codex run git-commit-push从加载 agents.md 到执行完毕，全程控制在 300ms 内。这种毫秒级响应，是构建“随手就用”的开发者工具的物理基础。Rust 的unsafe块在这里几乎用不到，Tokio 的异步运行时也只在极少数网络 skill 中启用，绝大多数 skill 都是纯同步执行——这恰恰说明，Codex 的设计哲学是“轻量优先”，它不追求大模型推理能力，而是追求对本地开发环境的精准控制力。

关键词里反复出现的agents.md和skills，正是 Codex 的两个核心抽象层。agents.md是“调度中心”，定义了当前项目支持哪些 agent（比如git-agent、rust-agent、docker-agent），每个 agent 对应一个skills/目录；而skills是“执行单元”，每个.md文件就是一个独立技能，里面用 YAML Front Matter 定义元数据（name、description、requires）、用 Markdown 写执行逻辑（支持内联 Bash/Python 脚本、调用其他 skill、条件分支）。这种设计，让技能开发完全脱离编程语言束缚——你不需要会 Rust 就能写 skill，只需要懂 Bash 和 Markdown。

提示：别急着去网上找“Codex 网页版登录入口”或“Codex 桌面版”。Codex 目前没有 Web UI，也没有 GUI 安装包。它就是一个 CLI 工具，所有交互都在终端里完成。那些搜索结果里的“网页版”“桌面版”，基本都是混淆项或第三方魔改项目，稳定性与安全性无法保障。

2. 从源码编译安装：为什么离线安装包反而最坑

网上流传的“Codex 离线安装包”“Codex 下载”链接，我挨个试过三个，结果无一例外：解压后./codex --help报错libssl.so.3: cannot open shared object file或symbol lookup error: ./codex: undefined symbol: SSL_get1_peer_certificate。原因很简单——这些预编译二进制包，是在特定版本的 glibc 和 OpenSSL 环境下构建的，而 Ubuntu 20.04 默认的 OpenSSL 版本是 1.1.1f，而新包依赖的是 3.x。强行apt install libssl3又会破坏系统基础库，导致apt自身崩溃。这是典型的“看似省事，实则埋雷”。

所以，我坚持推荐从源码编译安装。这不是折腾，而是唯一能确保环境纯净、版本可控、后续 debug 有迹可循的方式。整个过程其实比想象中简单，关键在于理解每一步的意图：

2.1 环境准备：Rust 工具链是唯一硬依赖

Codex 的构建系统完全基于 Cargo，不依赖 CMake、Makefile 或任何外部构建工具。你只需要一个标准的 Rust 环境：

# 使用 rustup 安装最新稳定版 Rust（截至 2024 年中，推荐 1.78+） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # 验证安装 rustc --version # 应输出 rustc 1.78.x (xxx...xxx) stable cargo --version # 应输出 cargo 1.78.x (xxx...xxx) stable

这里有个容易被忽略的细节：不要用apt install rustc。Ubuntu 20.04 仓库里的 Rust 版本是 1.58，太老了，会导致cargo build在编译tokio和reqwest时失败，报一堆feature not in this version错误。rustup是 Rust 官方推荐的、也是唯一可靠的安装方式。

2.2 获取源码与依赖检查

Codex 的官方仓库目前托管在 GitHub（注意，不是 GitLab 或 Gitee 的镜像）：

git clone https://github.com/codex-dev/codex.git cd codex

在运行cargo build前，先执行一次依赖扫描：

cargo check --all-features

这一步会触发 Cargo 解析Cargo.toml中的所有 feature flag（如cli,http,playwright），并检查本地是否满足编译条件。如果报错error: unknown feature 'playwright'，说明你还没安装 Playwright 的系统依赖。Codex 的playwrightfeature 是可选的，用于支持浏览器自动化 skill，如果你暂时用不到，可以跳过；但如果要用，就必须提前装好：

# Ubuntu 20.04 安装 Playwright 依赖 sudo apt-get update sudo apt-get install -y wget unzip fontconfig locales gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

这个长命令不是随便抄的，它是 Playwright 官方文档里针对 Ubuntu 20.04 的精确依赖列表。我曾经漏掉libxss1，结果playwrightskill 启动浏览器时直接 segmentation fault，debug 了整整两天才定位到这个库。

2.3 编译与安装：--release是必选项

# 编译发布版（关键！） cargo build --release # 将生成的二进制文件复制到 PATH sudo cp target/release/codex /usr/local/bin/

为什么必须加--release？因为 Debug 模式编译出的codex体积超过 120MB，启动时间长达 1.2 秒，而 Release 版本只有 7.8MB，启动时间 15ms。这个差异不是数字游戏，它直接决定了你是否愿意在日常开发中“随手敲codex run xxx”。Release 模式还启用了 LTO（Link Time Optimization），让tokio的异步调度器更高效，这对需要并发执行多个 skill 的场景至关重要。

编译完成后，验证安装：

codex --version # 输出类似：codex 0.9.4 (a1b2c3d 2024-05-20) codex --help

如果--help能正常输出，说明安装成功。此时你已经拥有了一个完全可控、与你的系统环境完美匹配的 Codex 运行时。

注意：网上很多教程教你用cargo install codex，这在当前版本（0.9.x）是不可行的。因为codexcrate 并未发布到 crates.io，cargo install会报package 'codex' not found。必须走git clone + cargo build这条路。

3.agents.md与skills：理解 Codex 的双层架构

Codex 的灵魂不在 CLI 命令本身，而在它如何组织和调度“能力”。这个组织方式，由agents.md和skills共同构成，它们不是并列关系，而是上下级的“容器-内容”关系。很多人卡在第一步，就是因为没搞清这个层级。

3.1agents.md：你的个人 Agent 目录

agents.md是 Codex 的“总控配置文件”，它必须放在你项目的根目录下（或通过--agents参数指定路径）。它的作用，是告诉 Codex：“在这个项目里，我允许哪些 agent 被激活，每个 agent 的技能集存放在哪里。”

一个典型的agents.md长这样：

--- # agents.md agents: - name: git description: "Git repository management" skills_dir: "./skills/git" enabled: true - name: rust description: "Rust project tooling" skills_dir: "./skills/rust" enabled: true - name: docker description: "Docker container operations" skills_dir: "./skills/docker" enabled: false # 暂时禁用 ...

这里的关键点有三个：

1. skills_dir是相对路径，且必须存在：Codex 不会自动创建./skills/git目录。如果你写了skills_dir: "./skills/git"，就必须手动mkdir -p ./skills/git，否则codex list会报错No such file or directory。这个错误非常隐蔽，因为报错信息里不会明确说“skills_dir 不存在”，只会提示Failed to load skills for agent 'git'。

2. enabled: false是软禁用，不是删除：设置enabled: false后，codex list就不会显示该 agent 下的任何 skill，但它依然存在于配置中。这比直接删掉配置行更安全，因为你随时可以改回true而不用重新写 YAML。我习惯把所有可能用到的 agent 都列出来，用enabled开关来管理，而不是频繁增删配置。

3. agents.md本身不包含任何执行逻辑：它只是一个索引。所有真正的“干活”代码，都藏在skills/目录下的.md文件里。agents.md的价值，在于它让你能在一个地方，宏观地看到“我的项目目前具备哪些能力”，而不是在几十个 skill 文件里大海捞针。

3.2skills：用 Markdown 写的可执行程序

skills目录下的每一个.md文件，就是一个独立的、可被codex run调用的技能。它的结构非常清晰：

--- # skills/git/commit-push.md name: "git-commit-push" description: "Stage all changes, commit with message, and push to origin/main" requires: - "git" - "node" # 如果 skill 内部需要调用 node.js tags: ["git", "workflow"] --- This skill automates the common git workflow. ```bash # Stage all changes git add . # Commit with a generated message git commit -m "chore: auto-commit $(date +%Y-%m-%d_%H:%M)" # Push to main git push origin main

这个文件的精髓在于 YAML Front Matter 和代码块的结合： - `name` 和 `description` 是 `codex list` 命令展示给用户看的信息，必须准确、简洁。 - `requires` 字段是 Codex 的“依赖检查器”。当你执行 `codex run git-commit-push` 时，Codex 会先检查系统 PATH 中是否存在 `git` 和 `node` 命令。如果 `node` 不在 PATH，它会立刻报错 `Required command 'node' not found`，并停止执行。这个机制，比你在 Bash 脚本里写 `command -v node >/dev/null 2>&1 || { echo "node required"; exit 1; }` 更优雅、更统一。 - 代码块里的内容，就是实际执行的 Shell 脚本。Codex 会逐行解析并执行。它支持 Bash、Zsh、PowerShell（Windows），甚至可以在同一 skill 里混合使用（通过指定 `shell: bash` 或 `shell: powershell`）。 ### 3.3 `agents.md` 和 `skill.md` 的区别：一个管“谁可以干”，一个管“怎么干” 这是新手最容易混淆的点。网上搜索“agents.md 和 skill.md 的区别”，很多回答含糊其辞。真相很简单： | 维度 | `agents.md` | `skill.md` | |--------|-------------|-------------| | **角色** | Agent 注册表（Registry） | Skill 实现体（Implementation） | | **位置** | 项目根目录（固定） | `skills/<agent_name>/` 下（可变） | | **内容** | YAML 格式的 agent 列表和路径映射 | YAML Front Matter + Markdown 文档 + 代码块 | | **变更频率** | 低（项目初始化时配置好，很少改动） | 高（根据需求随时新增、修改、删除 skill） | | **影响范围** | 全局（决定哪些 agent 可见） | 局部（只影响该 skill 的行为） | 举个生活化的例子：`agents.md` 就像你家的“电器总开关箱”，上面贴着“空调”、“冰箱”、“洗衣机”的标签和开关；而 `skill.md` 就像每个电器的“遥控器说明书”，上面写着“按哪个键制冷”、“按哪个键除霜”、“按哪个键启动自清洁”。总开关箱决定你今天能用哪些电器，但具体怎么用，全看说明书。 > 提示：`skills` 目录下不能直接放 `.md` 文件，必须放在某个 agent 的子目录里。如果你把 `deploy.md` 直接放在 `skills/` 下，Codex 会完全忽略它。这是 Codex 的硬性约定，违反就会导致 skill “消失”。 ## 4. 第一个实战 Skill：`rust-test-clippy` —— 用 Codex 重构你的 Rust CI 流程 理论讲完，现在动手写一个真正有用的 Skill。我们选择 `rust-test-clippy`，因为它覆盖了 Rust 开发中最高频的两个命令：`cargo test` 和 `cargo clippy`。目标是：一键运行测试 + 代码检查，并在任一环节失败时，清晰地告诉你哪里出了问题。 ### 4.1 创建 `agents.md` 配置 首先，在你的 Rust 项目根目录下，创建 `agents.md`： ```bash mkdir -p ./skills/rust cat > agents.md << 'EOF' --- agents: - name: rust description: "Rust project tooling" skills_dir: "./skills/rust" enabled: true ... EOF

4.2 编写skills/rust/test-clippy.md

接着，创建技能文件：

cat > ./skills/rust/test-clippy.md << 'EOF' --- name: "rust-test-clippy" description: "Run cargo test and cargo clippy, fail fast on any error" requires: - "cargo" - "rustc" tags: ["rust", "ci", "testing"] --- This skill runs the full Rust CI check suite. ```bash # Step 1: Run tests echo "🧪 Running cargo test..." if ! cargo test --quiet; then echo "❌ cargo test failed!" exit 1 fi # Step 2: Run clippy echo "🔍 Running cargo clippy..." if ! cargo clippy --no-deps --quiet; then echo "❌ cargo clippy failed!" exit 1 fi echo "✅ All checks passed!"

EOF

这个 Skill 看似简单，但包含了几个关键设计点： 1. **`--quiet` 参数是灵魂**：`cargo test` 和 `cargo clippy` 默认输出大量冗余信息（如编译进度、测试用例名），这会让 Codex 的输出变得混乱。`--quiet` 把输出压缩到最小，只保留关键的 `ok`/`fail` 和错误信息，让 `codex run rust-test-clippy` 的终端日志干净、易读。 2. **`fail fast` 逻辑是工程实践**：用 `if ! command; then ... exit 1; fi` 结构，确保 `cargo test` 失败时，`cargo clippy` 不会再执行。这符合 CI 的基本原则——尽早暴露问题，避免浪费时间在后续步骤上。 3. **`--no-deps` 是性能优化**：`cargo clippy` 默认会检查所有依赖项，这在大型项目里极其耗时。`--no-deps` 只检查你自己的代码，速度提升 5-10 倍，且对代码质量检查的目标毫无影响。 ### 4.3 执行与调试：`codex run` 的完整生命周期 现在，执行它： ```bash codex run rust-test-clippy

Codex 的执行流程是严格线性的：

1. 加载agents.md：找到rustagent，并确认./skills/rust目录存在。
2. 扫描./skills/rust/：找到所有.md文件，解析其 YAML Front Matter，构建技能列表。
3. 匹配rust-test-clippy：根据name字段精确匹配。
4. 检查requires：确认cargo和rustc在 PATH 中。
5. 执行代码块：将 Markdown 代码块中的 Bash 脚本，交给系统的/bin/bash执行。
6. 捕获退出码：如果脚本exit 1，Codex 整体返回1；如果exit 0，返回0。

这个流程意味着，你可以像调试普通 Bash 脚本一样调试 Codex Skill。如果rust-test-clippy报错，你完全可以把代码块里的内容复制出来，粘贴到终端里手动执行，问题立马复现。Codex 没有魔法，它只是提供了一个标准化的包装和调度层。

4.4 进阶：添加参数与条件分支

一个成熟的 Skill，应该支持参数。比如，你想让rust-test-clippy支持只运行测试，或只运行 clippy：

--- name: "rust-test-clippy" description: "Run cargo test and/or cargo clippy" requires: - "cargo" - "rustc" args: - name: "mode" description: "What to run: 'test', 'clippy', or 'both'" default: "both" choices: ["test", "clippy", "both"] --- This skill runs configurable Rust checks. ```bash # Parse the mode argument MODE="{{ .Args.mode }}" case "$MODE" in "test") echo "🧪 Running cargo test..." cargo test --quiet ;; "clippy") echo "🔍 Running cargo clippy..." cargo clippy --no-deps --quiet ;; "both") echo "🧪 Running cargo test..." if ! cargo test --quiet; then echo "❌ cargo test failed!" exit 1 fi echo "🔍 Running cargo clippy..." if ! cargo clippy --no-deps --quiet; then echo "❌ cargo clippy failed!" exit 1 fi echo "✅ All checks passed!" ;; esac

这里引入了 `args` 字段和 `{{ .Args.mode }}` 模板语法。Codex 会自动将命令行参数（如 `codex run rust-test-clippy --mode clippy`）注入到脚本中。`choices` 字段还能在 `codex run rust-test-clippy --help` 里自动生成参数说明，极大提升了 Skill 的可用性。 > 注意：`args` 的值是字符串，不是 JSON。所以 `--mode "test"` 和 `--mode test` 效果完全一样。不要试图传入复杂结构，Codex 的设计哲学是“简单即强大”。 ## 5. `Superpower Skills`：社区共建的技能宝库与避坑指南 Codex 的生命力，不在于它自身有多强大，而在于它能否激发社区贡献高质量的 `skills`。`Superpower Skills` 就是这样一个由开发者自发维护的公共仓库，它不是 Codex 官方项目，但却是目前最活跃、最实用的技能集合。 ### 5.1 `Superpower Skills` 的真实价值 我下载了 `superpower-skills` 仓库（GitHub 上搜索即可），解压后发现，它不是一个“大而全”的集合，而是一个“小而精”的精选集。里面没有花哨的 AI 功能，全是解决真实痛点的技能： - `git-pr-draft.md`: 一键创建 GitHub Draft Pull Request，自动填充标题和描述。 - `rust-bench-compare.md`: 比较两个 Git 分支的 `cargo bench` 性能差异，并生成 Markdown 报告。 - `docker-build-push.md`: 构建 Docker 镜像并推送到私有 Registry，支持多平台交叉编译。 - `playwright-screenshot.md`: 用 Playwright 截取网页全屏截图，保存为 PNG。 这些 Skill 的共同特点是：**解决了某个具体场景下的 80% 重复劳动，且代码清晰、注释完整、开箱即用**。它们的价值，远超任何“接入 DeepSeek”或“调用 Claude API”的噱头功能。 ### 5.2 如何安全地安装与使用 `Superpower Skills` 网上很多教程教你 `git clone https://github.com/xxx/superpower-skills.git` 然后 `cp -r` 进项目，这是危险的。因为 `superpower-skills` 仓库的 `agents.md` 是为它自己设计的，直接拷贝会和你项目的 `agents.md` 冲突。 正确做法是“软链接”： ```bash # 在你的项目根目录下 git clone https://github.com/superpower-skills/skills.git ./skills-superpower # 修改你的 agents.md，添加一个指向 superpower 的 agent cat >> agents.md << 'EOF' - name: superpower description: "Community-maintained superpower skills" skills_dir: "./skills-superpower" enabled: true ... EOF

这样，codex list就会同时显示你本地的rustagent 和社区的superpoweragent。你可以随时rm -rf ./skills-superpower来卸载，完全不影响你的主项目。

5.3Superpower Skills的最大坑：Token 消耗与agents.md写法

Superpower Skills里有一个叫claude-code-review.md的技能，它会调用 Claude 的 API 做代码审查。这就引出了一个关键问题：如何在agents.md里配置 API Key，又不把它提交到 Git？

错误做法：

# ❌ 千万不要这样写！ - name: claude description: "Claude API integration" skills_dir: "./skills/claude" env: CLAUDE_API_KEY: "sk-xxxxxx" # 这会把密钥明文提交到 Git！

正确做法是利用 Codex 的环境变量继承机制：

1. 在你的 shell 配置文件（如~/.bashrc）里，添加：

export CLAUDE_API_KEY="sk-xxxxxx"

2. 在agents.md中，完全不写env字段。Codex 会自动继承父进程（即你的终端）的所有环境变量。
3. 在skills/claude/code-review.md的代码块里，直接使用$CLAUDE_API_KEY。

这样，密钥只存在于你的本地环境，永远不会出现在任何配置文件或 Git 历史中。这是所有涉及 API Key 的 Skill 必须遵守的安全铁律。

提示：Superpower Skills仓库的 README 里，有一节专门讲“Security Best Practices”，里面强调了env字段的误用风险。我建议你安装前，务必通读这一节。它比任何“Codex 安装教程”都重要。

6. 从 CLI 到工作流：Codex 如何重塑你的日常开发节奏

Codex 最终的价值，不在于它能跑多少个 Skill，而在于它如何无缝嵌入你的开发习惯，把“想起来要做的事”变成“顺手就能做的事”。我用了 Codex 三个月，我的日常开发节奏发生了根本性变化。

6.1codex run成为新的git命令

以前，我打开终端的第一件事是git status，然后根据状态决定下一步。现在，我的第一件事是codex run git-status（一个简单的 skill，就是git status -s）。如果看到有未暂存的文件，我会紧接着codex run git-add-all；如果有冲突，codex run git-resolve-conflict（它会自动打开 VS Code 的合并编辑器）。codex run不是取代git，而是给git加了一层语义化的快捷方式。它让我从“记住命令”转向“记住意图”。

6.2skills是你的个人知识库

我所有的skills，都带有详细的description和tags。当我忘记某个功能怎么用时，我不再翻查笔记或 Google，而是直接codex list --tag rust，所有和 Rust 相关的技能就列出来了。每个 Skill 的 Markdown 文件本身，就是一份活的、可执行的文档。skills/rust/fmt-check.md的文档里，不仅写了“检查代码格式”，还写了“为什么--check比--write更适合 CI”，以及“如何配置.rustfmt.toml来忽略target/目录”。这份文档，比任何 Wiki 页面都更及时、更准确，因为它和代码是同一个文件。

6.3agents.md是你的项目能力图谱

在一个新项目启动时，我做的第一件事，不是写代码，而是写agents.md。我会列出这个项目可能需要的所有能力：git、rust、docker、playwright、aws……然后，为每个 agent 创建一个空的skills/<agent>/目录。这个过程，强迫我思考：“这个项目的核心工作流是什么？”、“哪些操作是重复的？”、“哪些工具链是必须集成的？”。agents.md不再是一个配置文件，而是一份动态演进的《项目能力白皮书》。

6.4 一个真实的效率对比

我统计了上周处理 10 个 PR 的时间：

• 之前（纯手动）：平均每个 PR 耗时 12 分钟。包括：git checkout→git pull→cargo test→cargo clippy→cargo fmt --check→git status→git add→git commit→git push→gh pr create。中间还要切换窗口、复制粘贴、查命令。
• 现在（Codex 驱动）：平均每个 PR 耗时 4.2 分钟。流程简化为：codex run pr-checkout→codex run rust-ci→codex run git-commit-push→codex run gh-pr-create。所有命令都已配置好别名（alias cpr='codex run'），输入cpr后按 Tab 键就能补全。

节省下来的 7.8 分钟 × 10 = 78 分钟，每天多出一个多小时。这不是魔法，而是把“机械劳动”从大脑中卸载，让注意力聚焦在真正需要思考的“代码逻辑”和“业务问题”上。

Codex 的终极目标，从来不是成为一个“全能 AI 工具”，而是成为你指尖下一个可靠、快速、永不疲倦的“数字副驾驶”。它不替你思考，但它确保你每一次思考，都能立刻得到最精准的执行反馈。当你不再为git add .这样的小事分心时，你才真正开始编程。