上手 Codex Harness：安装、配置、跑通第一个任务

Author: zhiqiu16 | Create: 2026-08-23 11:07:59 | Update: 2026-08-25 09:53:57 | 分类：智能体与 Harness

教程CLICodexHarnessMCP

OpenAI 把 Codex 的 Agent 执行框架开源之后（Apache-2.0，仓库 github.com/openai/codex），最常被问的问题变成了很实际的一个：怎么装，怎么用？

这篇就只讲这个。所有命令和配置项都核对自当前仓库源码，不是抄 2025 年的老教程——后面会专门列一节说明哪些老写法已经失效了。

一、安装

四选一，按你的习惯来。

# 1. 官方安装脚本(macOS / Linux)

curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 2. npm

npm install -g @openai/codex

# 3. Homebrew(macOS)

brew install --cask codex

Windows 用 PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

第四种是直接下二进制。GitHub Releases 里有预编译包，文件名带平台标识：

codex-aarch64-apple-darwin.tar.gz（Apple Silicon Mac）
codex-x86_64-apple-darwin.tar.gz（Intel Mac）
codex-x86_64-unknown-linux-musl.tar.gz
codex-aarch64-unknown-linux-musl.tar.gz

解压后重命名为 codex 丢进 PATH 就行。

小坑：安装脚本默认从 releases.openai.com/codex 拉包，这个域名在部分网络环境下不通。设 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false 可以强制走 GitHub Releases。

二、登录

直接跑 codex 会进 TUI，第一次会引导你选 "Sign in with ChatGPT"，走浏览器授权。支持 Plus / Pro / Business / Edu / Enterprise 订阅。

如果你在服务器上、没有浏览器，或者想用 API key：

codex login # 默认:浏览器 ChatGPT 登录

codex login --device-auth # 无头/远程机器:设备码登录

codex login status # 看当前登录状态

codex logout

# 用 API key(从 stdin 读,避免落进 shell history)

printenv OPENAI_API_KEY | codex login --with-api-key

# 用 access token

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

注意：codex login --api-key KEY 这个老写法已废弃，现在会提示你改用 --with-api-key 从 stdin 读。老教程里到处都是前者，别照抄。

三、三种用法

3.1 交互模式（TUI）

codex

进去就是一个终端里的对话界面。v0.149.0 之后新增了几个斜杠命令：/cd、/pwd、/cwd，切工作目录不用退出来了。

3.2 `codex exec`：非交互，跑完就退

这是接 CI/CD 和脚本的主力：

# 单次任务

codex exec "重构 src/utils.ts 里的 fetchData,加上错误处理"

# 指定工作目录

codex exec -C /path/to/project "跑测试并修复失败用例"

# 从 stdin 读 prompt

echo "总结这个仓库的架构" | codex exec

codex exec - "明确从 stdin 读"

# 会话管理

codex exec resume <SESSION_ID> # 恢复指定会话

codex exec resume --last # 恢复最近一次

codex exec resume --all # 列出所有会话(不按 cwd 过滤)

codex exec fork <SESSION_ID> # 从历史会话 fork 一条新的

# 代码评审

codex exec review --uncommitted # 评审未提交的改动

codex exec review --base main # 评审相对 main 分支的改动

codex exec review --commit <sha> # 评审某次提交

常用 flag：

Flag 作用
`--json`	事件以 JSONL 打到 stdout，机器可读
`-o, --output-last-message <file>`	把 agent 最后一条消息写进文件
`--output-schema <file>`	指定输出的 JSON Schema，拿结构化结果
`--skip-git-repo-check`	允许在非 git 目录里跑
`--ephemeral`	不落盘会话文件
`--strict-config`	config.toml 有未知字段就报错（强烈建议开）
`--ignore-user-config`	不加载 `$CODEX_HOME/config.toml`
`-c key=value`	命令行临时覆盖配置项

在 CI 里跑，典型组合是：

codex exec --json --skip-git-repo-check \

-c approval_policy=never \

-o /tmp/result.txt \

"修复 lint 报错并提交"

3.3 子命令全集

codex 下面还有一堆：agents（v0.149.0 新增的 agent 管理看板）、mcp、mcp-server、app-server、doctor、sandbox、execpolicy、queue、debug、exec-server。

其中 codex queue --thread-id <id> "消息" 挺实用——给一个正在跑的会话排队追加消息，不用等它停下来。

四、配置文件

位置：~/.codex/config.toml（CODEX_HOME 环境变量可以改主目录）。会话历史存在 ~/.codex/sessions。

一份能直接用的示例：

# ~/.codex/config.toml

model = "gpt-5.6"

model_provider = "openai"

# ---- 接第三方 / 兼容端点 ----

[model_providers.my_provider]

base_url = "https://api.example.com/v1" # 任意 OpenAI 兼容端点

env_key = "MY_API_KEY" # 从哪个环境变量读 key

requires_openai_auth = false # false 则跳过登录屏,直接用 env_key

# ---- 审批与沙箱 ----

approval_policy = "on-request" # "on-request" | "never" | { granular = {...} }

sandbox_mode = "workspace-write" # "read-only" | "workspace-write" | "danger-full-access"

[sandbox_workspace_write]

network_access = false # 沙箱内是否放行网络,默认 false

writable_roots = ["/abs/path/to/cache"] # 工作区之外额外允许写的目录

# exclude_slash_tmp = false

# exclude_tmpdir_env_var = false

# ---- MCP server ----

[mcp_servers.filesystem]

command = "npx"

args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

# ---- 按项目设信任级别 ----

[projects."/abs/path/to/project"]

trust_level = "trusted" # "trusted" | "untrusted"

其他值得知道的键：

model_reasoning_effort — 推理强度
model_reasoning_summary — auto | concise | detailed | none
service_tier — default | priority | flex
approvals_reviewer — user | auto_review | guardian_subagent，决定审批请求路由给谁
profiles — 命名 profile，叠加 $CODEX_HOME/<name>.config.toml

model_providers 下每个 provider 还支持 http_headers、env_http_headers、query_params、request_max_retries、stream_idle_timeout_ms、auth（命令产出 bearer token）、aws（SigV4 签名）等一堆细项，接私有网关够用了。

环境变量 OPENAI_API_KEY 和 OPENAI_BASE_URL 依然有效。

五、沙箱与审批（这节最重要）

Codex 默认会在你的真实文件系统上执行命令。沙箱和审批是唯一的闸门，值得花时间搞明白。

三档沙箱

`sandbox_mode` 含义
`read-only`	文件系统只读，默认禁网
`workspace-write`	工作区 + `writable_roots` 可写，`network_access` 默认关
`danger-full-access`	不沙箱，完全放行（名字已经很诚实了）

各平台怎么实现的

macOS → Seatbelt。源码在 codex-rs/sandboxing/src/seatbelt.rs，配套几个 .sbpl 策略文件。
Linux → bubblewrap 为默认，Landlock 退成 legacy 回退路径。优先用 PATH 上的 bwrap，找不到就用内置的；配合 PR_SET_NO_NEW_PRIVS 和 seccomp 网络过滤，--ro-bind / / 挂只读根，再逐层 --bind 出可写路径，.git 和 .codex 这类敏感子目录会被重新挂回只读。
Windows → restricted token 沙箱（codex-rs/sandboxing/src/windows.rs）。

想强制走老的 Landlock 路径：-c features.use_legacy_landlock=true。

WSL 用户注意：WSL2 走正常的 bubblewrap 路径没问题；WSL1 不支持——建不了 user namespace，需要沙箱的命令会直接被拒。

审批策略

approval_policy 当前只有三种形态：

"on-request" — 模型自己判断什么时候该问你
"never" — 从不询问，失败直接把错误回给模型
{ granular = { mcp_elicitations, request_permissions, rules, sandbox_approval, skill_approval } } — 细粒度布尔开关

execpolicy：规则引擎

除了 approval_policy，还有一套独立的命令白名单引擎，用 Starlark 语法写规则：

prefix_rule(pattern=["git", "status"], decision="allow")

prefix_rule(pattern=["rm", "-rf"], decision="forbidden")

prefix_rule(pattern=["npm", "publish"], decision="prompt")

验证规则：

codex execpolicy check --rules path/to/policy.rules git status

在团队里推 Codex，这套东西比模型能力更值得先配好。

六、AGENTS.md

项目根目录放一份 AGENTS.md，Codex 进到这个仓库时会自动当作持久上下文加载。里面写编码规范、命令约定、目录结构说明、注意事项——相当于给 Agent 的项目入职文档。

Codex 仓库自己就有一份，用来约束 codex-rs/ 的 Rust 写法。

关于「子目录能不能各放一份」「有没有全局 ~/.codex/AGENTS.md」这类层级规则，2025 年的文档有过一套说法，但当前官方已把这部分挪到 developers.openai.com/codex/guides/agents-md。以官方 guides 页为准，别按老文档的层级假设来组织。

七、MCP：双向都支持

Codex 当 MCP client（挂别人的工具）

两条路。一是写进 config.toml（见上面的 [mcp_servers.filesystem] 示例），支持 stdio（command + args）和远程（url）两种。二是用 CLI 管理：

codex mcp # 管理 config.toml 里的 MCP server 启动器

每个 server 还能配 enabled_tools / disabled_tools 做工具级别的裁剪，startup_timeout_ms、tool_timeout_sec 控超时。工具一多，这些开关很关键。

Codex 当 MCP server（把自己接给别人）

codex mcp-server

# 调试

npx @modelcontextprotocol/inspector codex mcp-server

暴露出去的 v2 RPC 包括 thread/start、thread/resume、thread/fork、turn/start、turn/steer、turn/interrupt、account/read、model/list、config/read。审批走反向请求——server 向 client 发 applyPatchApproval / execCommandApproval，client 返回 { decision: "allow" | "deny" }。

这个接口官方标注为 experimental，接之前有心理准备。

八、SDK

TypeScript

npm install @openai/codex-sdk # Node 18+

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();

const thread = codex.startThread();

const turn = await thread.run("诊断测试失败的原因并给出修复方案");

console.log(turn.finalResponse, turn.items);

// 流式

const { events } = await thread.runStreamed("...");

// 结构化输出(可以配 zod-to-json-schema)

await thread.run(prompt, { outputSchema: schema });

// 恢复会话(线程持久化在 ~/.codex/sessions)

const resumed = codex.resumeThread(id);

坑：类名是 Codex，不是 CodexAgent。有些中文教程写的是后者，跟官方 README 对不上。

SDK 本质是拉起 codex CLI，走 stdin/stdout 的 JSONL 通信。工作目录用 startThread({ workingDirectory, skipGitRepoCheck }) 指定；换 base URL 用 --config openai_base_url=...。

Python

pip install openai-codex

from openai_codex import Codex

with Codex() as codex:

thread = codex.thread_start()

result = thread.run("用三句话说明这个仓库是做什么的")

print(result.final_response)

# 登录

# codex.login_chatgpt()

# codex.login_chatgpt_device_code()

# codex.login_api_key("sk-...")

九、app-server：做产品的那一层

如果你要把 Codex 嵌进 IDE 插件或者桌面应用，走这层：

codex app-server --stdio # 默认:stdio,JSONL + JSON-RPC 2.0

codex app-server --listen unix:// # Unix socket

codex app-server --listen ws://127.0.0.1:PORT # WebSocket(experimental)

codex app-server generate-ts --out DIR # 生成 TS 类型

codex app-server generate-json-schema --out DIR # 生成与当前版本绑定的协议 schema

三个核心原语：

Thread — 会话，可以 fork、可以 resume
Turn — 单轮交互
Item — 用户输入 / agent 输出的原子事件

生命周期：initialize（带 clientInfo）→ thread/start | thread/resume | thread/fork → turn/start → 流式收 item/* 和 turn/* 通知 → turn/completed（或者被 turn/interrupt 打断）。

监听 WebSocket 时有健康检查端点：GET /readyz 返 200；GET /healthz 不带 Origin 头返 200，带了返 403。

入口饱和时会返回 JSON-RPC 错误 -32001 "Server overloaded; retry later."，客户端记得做指数退避。

一个容易踩的坑：app-server 协议里字段是 camelCase（approvalPolicy: "never"、sandbox: "workspaceWrite"），而 config.toml 里是 snake_case（approval_policy、sandbox_mode），取值写法也不同。两套命名，别串了。

十、踩坑清单

按遇到的概率排序：

1. approval_policy 的老取值已经全部失效。 2025 年的文档里 always / on-failure / untrusted 这三个值，在当前 schema 里 grep 计数为零。"trusted / untrusted" 的语义已经迁移到 [projects."<path>"] trust_level。这是最容易照着老博客抄错的地方。

2. 配置键写错会被静默忽略。 加 --strict-config，让未知字段直接报错，别让一个拼写错误坑你半小时。

3. codex login --api-key 已废弃。 改用 printenv OPENAI_API_KEY | codex login --with-api-key。

4. 默认要求 git 仓库。 非 git 目录加 --skip-git-repo-check。

5. 网络排障先跑 codex doctor。它会检查端点连通性、代理配置、桌面 App 状态、更新通道。国内环境接中转的话，配 model_providers 的 base_url 或者环境变量 OPENAI_BASE_URL。

6. 权限 profile 静默回退的 bug。 v0.149.0 之前，resume 或 fork 之后权限 profile 会悄悄退回默认值。升到 0.149+ 就好了。

7. WSL1 用不了沙箱。 必须 WSL2。

最后

Codex Harness 这套东西真正的门槛不在安装——curl | sh 三十秒的事。门槛在于想清楚要给它多大权限。

sandbox_mode = "danger-full-access" 配上 approval_policy = "never"，确实爽，确实什么都能干。但那也意味着一个不确定的系统拿到了你机器的完全控制权，在无人值守的情况下跑。

先从 read-only 开始，跑顺了再放到 workspace-write，把 execpolicy 规则写好，再考虑更激进的配置。这个顺序，比任何 prompt 技巧都重要。

本文命令与配置项核对自 openai/codex 仓库源码（Apache-2.0，对应 rust-v0.149.0，2026-08-23）。Codex 迭代很快，遇到对不上的地方以仓库内 config.schema.json 和各 README 为准。

暂无评论，来抢沙发～