核心概念

刚开始用 Codex，最容易卡住的不是命令，而是一堆名词：线程、上下文、沙箱、审批、AGENTS.md、Skills、MCP、子代理……它们各管一件事，但互相关联。这一页每个概念讲一小节：它是什么、你什么时候会碰到、怎么控制它。后面的专题页会展开细节，这里先搭好整体框架。

Agent 循环

Codex 处理一个请求，不是「问一次、答一次」，而是一个循环：

text

你的请求
  └─> 模型思考：现在该做什么？
        ├─ 调用工具：读文件 / 搜索 / 改文件 / 运行命令 / 调 MCP 工具
        │     └─> 工具结果返回给模型 ─┐
        │                              │
        └──────────── 再次思考 <───────┘
  直到：任务完成 → 给你总结；或者需要你确认 → 停下来问你

一次「轮次」（turn）里，模型可能连续调用几十次工具。比如你说「修好失败的测试」，它会先跑测试看报错，打开相关源码，改一处，再跑测试，发现还有一个失败，再改……直到全部通过才回来汇报。

理解这一点有两个实际用处：

给它验证手段。循环靠工具结果纠错，项目里有测试、有 lint、有能运行的命令，它就能自己发现错误；什么都没有，它只能「觉得」自己做对了。
中途可以插话。循环进行中按 Esc 能打断它；也可以直接输入新消息，用 Tab 排队，等当前步骤结束后再交给它。

先计划再动手

复杂任务可以先切到计划模式（输入 /plan，或按 Shift+Tab 在协作模式间切换）。这时 Codex 只调查和出方案，不改文件，你认可后再让它执行。

会话（线程）

一个会话，官方也叫线程（thread），就是你的一串请求加上 Codex 的所有回复和工具调用记录。本地会话保存在 ~/.codex/sessions/ 下，所以关掉终端也不会丢：

操作	CLI 命令 / 斜杠命令
开一个新会话	会话内 `/new`，或重新运行 `codex`
恢复以前的会话	`codex resume`（弹出列表）、`codex resume --last`，会话内 `/resume`
从当前会话分叉一条新线	会话内 `/fork`，或 `codex fork`
给会话起名	`/rename`
归档 / 删除	`/archive`、`/delete`，或 `codex archive` / `codex delete`

几条使用习惯：一个会话只做一件事；换话题就 /new，不要把十个不相关的任务塞进同一个会话；多个会话同时跑时，避免它们改同一批文件，需要并行改代码时用 Worktree。

上下文窗口与压缩

模型每次思考时能「看到」的内容是有限的，这个上限叫上下文窗口，用 token 计量。会话里的所有东西都要占用它：你的消息、Codex 读过的文件内容、命令输出、它自己的回复，以及 AGENTS.md、Skills 列表这些自动带上的说明。

会话越长，占用越多。快满的时候有两种处理办法：

压缩（compact）：把前面的对话总结成一段摘要，用摘要替换原始记录，腾出空间继续。Codex 默认开启自动压缩，接近上限时会自动做；你也可以随时输入 /compact 手动压缩。
开新会话：/new 之后从零开始，最干净。

输入 /status 可以查看当前会话的模型、配置和 token 用量。

压缩会丢细节

摘要保留的是要点，具体的报错原文、某个文件的完整内容、你五十条消息前顺口提的要求，压缩后可能就没了。重要的约定写进 AGENTS.md，阶段性结论让它写到文件里（比如 PLAN.md），比指望它「记住」可靠。

工作目录

Codex 在哪个目录启动，那个目录就是它的工作根目录（workspace）：读文件从这里找，默认只能写这里面的文件，AGENTS.md 也从这里往上找。

bash

cd ~/projects/my-app && codex        # 以 my-app 为工作目录
codex -C ~/projects/my-app           # 不切换目录，直接指定
codex --add-dir ../shared-lib        # 额外允许写另一个目录

会话里可以用 /pwd 查看、/cd 切换当前工作目录。

第一次在某个目录启动时，Codex 会询问是否信任这个文件夹。信任后，这个项目里的 .codex/config.toml、钩子、命令规则等项目级配置才会生效；不信任的目录以受限方式打开。不要在家目录或磁盘根目录直接启动，那样它的「工作区」就是你整个硬盘。

沙箱模式与审批策略

这是两个独立但配合使用的开关：

沙箱模式（sandbox） 决定 Codex 运行的命令在技术上能做什么：只读、只能写工作区、还是完全不受限。它由操作系统级别的机制强制执行（macOS 的 Seatbelt、Linux 的 bubblewrap/Landlock、Windows 的专用沙箱），不是靠模型自觉。
审批策略（approval policy） 决定什么时候停下来问你。

沙箱模式	含义
`read-only`	只能读，改文件和联网都要审批
`workspace-write`	能读写工作区、运行命令，联网和写工作区外要审批
`danger-full-access`	不受限，谨慎使用

审批策略	含义
`untrusted`	只有已知安全的只读命令自动执行，其他都问
`on-request`	由模型判断，需要越过沙箱时再问（默认）
`never`	从不询问，失败直接返回给模型

日常不用记这些组合：会话里输入 /permissions，从 Read Only、Default、Full Access 三个预设里选即可，默认就是 Default（工作区可写 + 按需审批）。完整说明、granular 细粒度审批和各平台差异见沙箱与审批。

AGENTS.md

AGENTS.md 是写给智能体看的项目说明书，纯 Markdown，没有固定格式。Codex 每次开新会话都会自动读取并放进上下文，所以写在里面的约定会一直生效：

markdown

# AGENTS.md

- 包管理用 pnpm，不要用 npm
- 改完 TypeScript 文件后运行 `pnpm typecheck` 和 `pnpm test`
- 不要修改 `migrations/` 下已有的文件，需要改表就新建迁移

查找规则：先读 ~/.codex/AGENTS.md（个人全局习惯），再从项目根目录（默认以 .git 所在目录为根）一路往下，读到当前工作目录为止，每一层的 AGENTS.md 都会拼接进来，越靠近当前目录越靠后、越具体。同一目录下如果有 AGENTS.override.md，就用它代替 AGENTS.md。合计内容默认上限 32 KiB，超出部分会被截断。

在项目里输入 /init，Codex 会扫描项目帮你起草一份。写法和分层技巧见 AGENTS.md。

Skills

Skill（技能）是一个文件夹，核心是一份 SKILL.md：开头的元数据写名字和「什么时候该用」，正文写具体做法，旁边可以放脚本、模板、参考资料。

和 AGENTS.md 的区别在于加载方式：AGENTS.md 每次全文加载；Skill 平时只把名字和简介放进上下文，Codex 判断当前任务用得上时才读取全文。所以你可以装很多 Skill 而不撑爆上下文，适合放「发版流程」「写周报格式」「某个内部 API 的用法」这类按需取用的知识。

个人 Skill 放在 ~/.agents/skills/（旧位置 ~/.codex/skills/ 仍兼容），项目 Skill 放在仓库的 .agents/skills/。会话里输入 /skills 查看和调用，或在消息里用 $技能名 点名使用。详见 Skills。

MCP

MCP（Model Context Protocol）是一个开放协议，让智能体能调用外部工具和数据源。接入一个 MCP 服务器，Codex 就多出一组工具，比如查数据库、读 Figma 设计稿、操作浏览器、查内部文档。

bash

codex mcp add docs -- npx -y some-docs-mcp-server   # 添加一个本地 MCP 服务器
codex mcp list                                       # 查看已配置的服务器

配置最终写在 config.toml 的 [mcp_servers.名字] 下。会话里 /mcp 可以查看当前可用的 MCP 工具。另外，Codex 自己也能作为 MCP 服务器运行（codex mcp-server），供其他智能体调用。详见 MCP。

子代理

主代理可以派生子代理（subagent）去完成子任务，每个子代理有自己独立的上下文，做完只把结论交回来。好处是主会话的上下文不会被大量探索过程塞满，几个子任务也能同时进行。

内置的角色有 explorer（专门回答代码库里的具体问题）和 worker（负责执行和改代码）；你也可以在配置里定义自己的角色，给它们指定不同的模型和推理强度。会话里 /agents 打开代理面板，/subagents 在子代理之间切换查看。详见子代理。

模型与推理强度

模型决定能力上限和价格。通过 HiveGPT 接入时默认是 gpt-5.5；可选的其他模型以会话里 /model 列出的为准。

推理强度（reasoning effort）决定模型回答前「想多久」，常见档位是 low、medium、high、xhigh，有的模型还有 minimal 或 max，具体支持哪些由模型决定。想得越久，复杂问题越靠谱，但速度越慢、消耗的 token 越多。

toml

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"

会话里 /model 可以同时切换模型和推理强度，Alt+, / Alt+. 能快速降低或提高推理强度。经验是：日常改代码用默认档，排查疑难 bug 或做架构设计时调高，批量简单修改时调低。详见模型与推理强度。

概念关系一览

概念	管什么	存在哪里 / 怎么设置	常用入口
Agent 循环	任务如何一步步执行	内置行为	`Esc` 打断、`/plan`
会话	一次任务的完整记录	`~/.codex/sessions/`	`/new`、`codex resume`
上下文窗口	模型一次能看到多少	由模型决定	`/status`、`/compact`
工作目录	在哪里读写	启动目录、`-C`、`--add-dir`	`/cd`、`/pwd`
沙箱	命令能做什么	`sandbox_mode`、`-s`	`/permissions`
审批策略	什么时候问你	`approval_policy`、`-a`	`/permissions`
AGENTS.md	每次都要遵守的约定	全局 + 项目各级目录	`/init`
Skills	按需加载的专项做法	`~/.agents/skills/`、`.agents/skills/`	`/skills`、`$技能名`
MCP	外部工具和数据	`[mcp_servers.*]`	`codex mcp`、`/mcp`
子代理	把子任务分出去	`[agents]` 配置	`/agents`
模型与推理强度	能力、速度、成本	`model`、`model_reasoning_effort`	`/model`

把它们串起来看：你在某个工作目录里开一个会话，Codex 带着 AGENTS.md 和 Skills 简介进入 Agent 循环，用选定的模型和推理强度思考，通过内置工具和 MCP 工具干活，必要时派子代理分担；每一次命令执行都受沙箱约束，越界时按审批策略来问你；会话变长后靠压缩维持在上下文窗口之内。

小结

Codex 以 Agent 循环工作：思考、调用工具、看结果、再思考，直到完成或需要你确认。
会话保存在本地，可恢复、分叉；上下文有上限，靠自动或手动 /compact 压缩，重要信息写进文件。
沙箱管「能做什么」，审批管「什么时候问」，日常用 /permissions 的三个预设即可。
AGENTS.md 每次全文加载，Skills 按需加载，MCP 扩展外部工具，子代理分担子任务。
模型和推理强度在 /model 里切换，难题调高，简单批量活调低。

下一步：安装与登录

核心概念 ​

Agent 循环 ​

会话（线程） ​

上下文窗口与压缩 ​

工作目录 ​

沙箱模式与审批策略 ​

AGENTS.md ​

Skills ​

MCP ​

子代理 ​

模型与推理强度 ​

概念关系一览 ​

小结 ​