Codex 目录结构与配置说明详解
这份文档基于当前目录 C:\\Users\\用户名\\.codex 的实际内容整理,目标是帮助使用者从“能看懂目录”进一步走到“能理解 Codex 的运行机制、能力加载方式、会话持久化方式,以及哪些配置可以改、哪些文件最好不要手改”。 
codex客户端下载:https://codexdown.cn/
1. 先看整体:.codex 是什么
.codex 可以理解为 Codex Desktop/CLI 的“本地工作中枢”。它通常承担下面几类职责:
可以把它想象成下面这条链路:
#mermaid-svg-EOATvvVB8Vk6VkYW{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-EOATvvVB8Vk6VkYW .error-icon{fill:#552222;}#mermaid-svg-EOATvvVB8Vk6VkYW .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-EOATvvVB8Vk6VkYW .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-EOATvvVB8Vk6VkYW .marker{fill:#333333;stroke:#333333;}#mermaid-svg-EOATvvVB8Vk6VkYW .marker.cross{stroke:#333333;}#mermaid-svg-EOATvvVB8Vk6VkYW svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-EOATvvVB8Vk6VkYW p{margin:0;}#mermaid-svg-EOATvvVB8Vk6VkYW .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster-label text{fill:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster-label span{color:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster-label span p{background-color:transparent;}#mermaid-svg-EOATvvVB8Vk6VkYW .label text,#mermaid-svg-EOATvvVB8Vk6VkYW span{fill:#333;color:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW .node rect,#mermaid-svg-EOATvvVB8Vk6VkYW .node circle,#mermaid-svg-EOATvvVB8Vk6VkYW .node ellipse,#mermaid-svg-EOATvvVB8Vk6VkYW .node polygon,#mermaid-svg-EOATvvVB8Vk6VkYW .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-EOATvvVB8Vk6VkYW .rough-node .label text,#mermaid-svg-EOATvvVB8Vk6VkYW .node .label text,#mermaid-svg-EOATvvVB8Vk6VkYW .image-shape .label,#mermaid-svg-EOATvvVB8Vk6VkYW .icon-shape .label{text-anchor:middle;}#mermaid-svg-EOATvvVB8Vk6VkYW .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-EOATvvVB8Vk6VkYW .rough-node .label,#mermaid-svg-EOATvvVB8Vk6VkYW .node .label,#mermaid-svg-EOATvvVB8Vk6VkYW .image-shape .label,#mermaid-svg-EOATvvVB8Vk6VkYW .icon-shape .label{text-align:center;}#mermaid-svg-EOATvvVB8Vk6VkYW .node.clickable{cursor:pointer;}#mermaid-svg-EOATvvVB8Vk6VkYW .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-EOATvvVB8Vk6VkYW .arrowheadPath{fill:#333333;}#mermaid-svg-EOATvvVB8Vk6VkYW .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-EOATvvVB8Vk6VkYW .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-EOATvvVB8Vk6VkYW .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EOATvvVB8Vk6VkYW .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-EOATvvVB8Vk6VkYW .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EOATvvVB8Vk6VkYW .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster text{fill:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW .cluster span{color:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-EOATvvVB8Vk6VkYW .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-EOATvvVB8Vk6VkYW rect.text{fill:none;stroke-width:0;}#mermaid-svg-EOATvvVB8Vk6VkYW .icon-shape,#mermaid-svg-EOATvvVB8Vk6VkYW .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EOATvvVB8Vk6VkYW .icon-shape p,#mermaid-svg-EOATvvVB8Vk6VkYW .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-EOATvvVB8Vk6VkYW .icon-shape .label rect,#mermaid-svg-EOATvvVB8Vk6VkYW .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EOATvvVB8Vk6VkYW .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-EOATvvVB8Vk6VkYW .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-EOATvvVB8Vk6VkYW :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}
启动 Codex
读取 AGENTS.md 与 config.toml
装载认证与全局状态
初始化模型供应商与 MCP Servers
加载 Skills / Plugins / Vendor Imports
执行对话、工具调用、自动化任务
写入 sessions / sqlite / jsonl / logs / cache
2. 顶层目录和文件速览
下面这些是当前 .codex 根目录里最值得关注的部分。
| AGENTS.md | 规则文件 | 给代理补充行为约束,比如输出风格、命令输出截断规则、代码注释要求。 |
| config.toml | 核心配置 | Codex 的总控配置入口,决定默认模型、供应商、MCP Server、项目信任等。 |
| auth.json | 敏感配置 | 存储认证信息,例如 OPENAI_API_KEY。 |
| .codex-global-state.json | UI/全局状态 | 保存窗口位置、最近工作区、线程关联信息、待处理 follow-up 等。 |
| session_index.jsonl | 会话索引 | 保存线程 ID、标题、更新时间,用于快速列出历史对话。 |
| sessions/ | 会话回放 | 按年月日分层存储实际对话回放文件,通常是 rollout-*.jsonl。 |
| state_5.sqlite | 主状态库 | 保存线程、任务、动态工具、后台作业等结构化状态。 |
| logs_2.sqlite | 日志库 | 保存运行日志、线程关联日志、模块名、文件行号等。 |
| goals_1.sqlite | 目标库 | 保存 thread goal、预算、tokens 使用量、耗时等。 |
| sqlite/codex-dev.db | 自动化库 | 保存 automations、automation runs、inbox items 等桌面端自动化数据。 |
| skills/ | 已安装技能 | 当前环境可直接使用的系统技能和本地技能。 |
| plugins/ | 插件缓存 | 已缓存的插件包及其版本化目录。 |
| vendor_imports/ | 外部技能源缓存 | 存储导入或同步下来的技能仓库及索引缓存。 |
| browser/ | 浏览器控制配置 | 保存浏览器能力相关配置与 session 白名单。 |
| computer-use/ | Computer Use 配置 | 保存桌面操作能力的本地配置。 |
| generated_images/ | 产物目录 | 存放生成图片的最终文件。 |
| ambient-suggestions/ | 建议缓存 | 保存基于项目上下文生成的环境建议缓存。 |
| node_repl/ | Node REPL 状态 | 保存活跃执行记录。 |
| rules/ | 规则文件 | 当前看到的 default.rules 更像命令放行规则集。 |
| .sandbox*、.tmp、tmp | 运行时目录 | 沙箱、临时插件、命令运行器等基础设施目录。 |
3. 核心入口文件
config.toml
这是最核心的人工可读配置文件。当前实例里,它主要承担 4 类职责:
模型选择 例如默认 model_provider、model、review_model、model_reasoning_effort、上下文窗口与自动压缩阈值。
模型供应商定义 当前配置里存在多个 provider,例如 OpenAI 和 CodexPlusPlus。 每个 provider 会定义:
- base_url
- wire_api
- 是否需要 OpenAI Auth
- 某些情况下的实验性 bearer token
MCP Server 注册 当前配置里已经注册了:
- chrome-devtools
- node_repl
- pascal
这意味着 Codex 不只是纯聊天,它会把浏览器控制、持久 Node 执行环境、Pascal 场景编辑等能力作为工具接入。
项目信任列表 [projects."…"] 这类段落表示哪些本地路径被标记为 trusted。 被信任的项目通常会影响:
- 工具可访问范围
- 本地操作安全策略
- 线程与工作区的绑定体验
AGENTS.md
这是对代理行为的“额外约束层”。 在当前目录下,它至少承担这些作用:
可以把它理解成“这个目录对代理的本地使用手册”。
auth.json
当前只观察到了 OPENAI_API_KEY 这个键名。 它是敏感文件,建议:
- 不要提交到 Git 仓库。
- 不要随意分享。
- 不要把完整内容直接贴到聊天记录或文档里。
.codex-global-state.json
这是 GUI/桌面态相关的全局状态文件。当前可见的键名表明它主要保存:
- 窗口位置与尺寸
- 最近工作区根目录
- 线程可写根路径
- follow-up 队列
- 远程连接回填状态
- 工程排序
- 项目与线程之间的提示映射
它更像“客户端外壳状态”,而不是模型行为配置。
4. 会话与历史是怎么存的
session_index.jsonl
这是历史线程的轻量索引。 每一行通常包含:
- id
- thread_name
- updated_at
它的作用是快速列出“最近有哪些线程”,而不必每次都扫描完整会话回放。
sessions/
当前目录结构是按时间分层的:
sessions/
2026/
05/
28/
rollout-2026-05-28T00-12-59-….jsonl
rollout-2026-05-28T15-15-17-….jsonl
这说明 Codex 会把详细会话回放按“年/月/日”归档。 rollout-*.jsonl 可以理解为线程执行过程的流水记录,通常比 session_index.jsonl 更细,适合:
- 排查某次会话到底发生了什么
- 回看工具调用链
- 分析代理行为
state_5.sqlite
这是结构化主状态库。当前表名显示它至少管理下面几类对象:
- threads
- jobs
- agent_jobs
- thread_dynamic_tools
- thread_spawn_edges
- stage1_outputs
- remote_control_enrollments
从字段看,threads 里保存的信息已经很完整,包括:
- 线程 ID、标题、创建/更新时间
- cwd
- model_provider
- model
- reasoning_effort
- sandbox_policy
- approval_mode
- tokens_used
- git_branch
- git_sha
- preview
这意味着 Codex 的线程并不只是“对话文本”,而是一个带有工作区、模型、Git、工具状态上下文的对象。
logs_2.sqlite
当前只看到一个主要表 logs,字段包含:
- 时间戳
- 日志级别
- target/module/file/line
- thread_id
- process_uuid
- estimated_bytes
它主要用于问题排查和运行观测。
goals_1.sqlite
当前看到的主表是 thread_goals,字段包含:
- thread_id
- goal_id
- objective
- status
- token_budget
- tokens_used
- time_used_seconds
这说明 Codex 的 goal 模式不是临时文本,而是持久化对象。
5. 自动化、提醒和收件箱
sqlite/codex-dev.db
当前库里看到的表包括:
- automations
- automation_runs
- inbox_items
- local_app_server_feature_enablement
这很像 Codex Desktop 里的“自动化中控库”:
- automations 保存定时或心跳自动化本体
- automation_runs 保存每次运行结果与线程关联
- inbox_items 像是给桌面端展示的待处理事项
如果你在 Codex 里创建“定时提醒”“定期执行任务”“稍后继续这个线程”,大概率会落到这类结构里。
6. Skills、Plugins、Vendor Imports 是怎么协同的
这是理解 Codex 扩展机制最关键的一部分。
skills/
当前可见两类内容:
其中 skills/.system/ 里已经存在:
- imagegen
- openai-docs
- plugin-creator
- skill-creator
- skill-installer
每个 skill 目录通常包含:
- SKILL.md
- agents/
- assets/
- references/
- scripts/
也就是说,Skill 不是单一提示词文件,而是一套“说明 + 参考资料 + 脚本 + 资源”的组合包。
plugins/
当前看到的是缓存结构:
plugins/cache/openai-primary-runtime/<plugin>/<version>/
plugins/cache/openai-bundled/chrome/<version>/
以 documents、presentations、spreadsheets 这些插件为例,每个版本目录中通常有:
- .codex-plugin/plugin.json
- skills/
- assets/
- README.md
其中 plugin.json 当前能看到的字段包括:
- name
- version
- description
- interface
- skills
- author
- repository
- homepage
- keywords
- license
这说明 Plugin 更像“可安装分发单元”,它可以把 Skill 一起打包交付。
vendor_imports/
当前结构显示这里缓存了一个技能仓库:
vendor_imports/
skills-curated-cache.json
skills/
.git/
README.md
skills/
.curated/
aspnet-core/
chatgpt-apps/
cli-creator/
…
这意味着 vendor_imports 更偏向“上游来源缓存”:
- 用来同步或导入第三方/官方技能源
- 本身可能保留 Git 元数据
- 通过 skills-curated-cache.json 做本地索引
简化理解:
- skills/ 是当前环境直接可用的技能
- plugins/ 是版本化插件包缓存
- vendor_imports/ 是技能来源仓库或导入缓存
7. 浏览器、Computer Use、Node REPL 这些能力怎么落地
browser/
当前包含:
- config.toml
- sessions/
browser/config.toml 当前只看到一类配置:允许来源白名单。
[origins]
allowed = ["http://127.0.0.1:4173"]
这说明浏览器集成能力会对允许连接的前端来源做限制。 browser/sessions/*.toml 则像浏览器控制会话的本地状态文件。
computer-use/
当前只有一个 config.json,字段包括:
- accentColor
- direction
- locale
- strings
这更像 Computer Use 界面层或本地化层配置,而不是业务逻辑。
computer-use-turn-ended/
当前目录下是大量以 UUID 风格命名的空文件。 它很像“某个 Computer Use 回合已经结束”的标记目录,用于:
- 去重
- 恢复状态
- 避免重复处理同一轮桌面操作
node_repl/
当前看到:
node_repl/
active_execs/
<exec-id>.json
执行元数据里包含的键名有:
- execId
- kernelPid
- nodeReplPid
- sandbox
- sessionId
- startedAtMs
- turnId
- version
这说明 Node REPL 是一个真正持续运行的执行环境,而不是一次性脚本。
8. 生成产物、建议缓存和小功能目录
generated_images/
每个子目录对应一次生成任务,里面可以看到类似:
generated_images/<task-id>/ig_xxxxx.png
也就是最终图片产物通常直接落在这里。
ambient-suggestions/
当前每个哈希目录里都有 ambient-suggestions.json。 键名显示它会记录:
- projectRoot
- generatedAtMs
- currentSuggestionIds
- suggestions
可以把它理解为“针对某个项目根目录生成过的一组环境建议缓存”。
pets/
当前每个宠物目录里有 pet.json,字段包括:
- id
- displayName
- description
- kind
- spritesheetPath
这更像桌面端陪伴/形象层资源,不属于核心执行链路,但属于产品外壳的一部分。
cache/
当前 cache/codex_apps_tools/*.json 里能看到:
- schema_version
- tools
这很像桌面端或应用层工具定义缓存。
9. 沙箱和临时目录
.sandbox/
当前包含:
- requests/
- sandbox.log
- setup_marker.json
- setup_error.json
- deny_read_acl_state.json
requests/*.json 里能看到这些字段:
- command
- cwd
- env_map
- policy_json_or_preset
- timeout_ms
- stdin_pipe
- stdout_pipe
- stderr_pipe
这说明即使当前会话未必强制使用沙箱,Codex 仍保留了一套完整的“命令请求与策略记录机制”。
.sandbox-bin/
这里放的是沙箱运行器或桥接可执行文件,例如:
- codex-command-runner.exe
- 不同版本的 codex-command-runner-*.exe
- codex.exe
它更偏底层基础设施。
.sandbox-secrets/
这里目前看到 sandbox_users.json,说明它与沙箱身份或访问控制有关。
.tmp/ 与 tmp/
这两个目录用于临时运行数据。当前看到的内容包括:
- 插件克隆目录
- marketplace 临时目录
- plugins.sha
- 过程性路径目录
这类目录通常不适合手动维护,问题排查时可以看,但不建议常规改动。
10. rules/default.rules 是什么
当前 rules/default.rules 的内容是大量:
prefix_rule(pattern=[…], decision="allow")
这说明它更像“命令前缀允许规则集”,用于:
- 记录已经放行的命令模式
- 避免重复确认
- 给运行器提供规则匹配依据
它不是传统意义上的产品主配置,更像执行安全层的辅助规则文件。
11. 哪些文件可以改,哪些最好别直接改
相对适合人工维护
- config.toml
- AGENTS.md
- skills/ 下你自己维护的技能目录
- 某些你明确知道用途的插件配置文件
可以查看,但修改前要很清楚后果
- .codex-global-state.json
- rules/default.rules
- browser/config.toml
- computer-use/config.json
不建议手动编辑
- auth.json
- session_index.jsonl
- sessions/**/*.jsonl
- state_5.sqlite
- logs_2.sqlite
- goals_1.sqlite
- sqlite/codex-dev.db
- .sandbox/**
- node_repl/active_execs/*.json
- generated_images/ 中的产物文件
原因很简单:这些文件多数是程序运行时持续读写的持久化数据,人工改错一个字段,就可能导致线程损坏、索引错乱、会话无法恢复。
12. 用“机制视角”再总结一次
如果你想真正理解 Codex,可以按下面这条思路记忆:
一句话概括:
.codex 不是简单的配置目录,而是 Codex 在本地的“配置中心 + 扩展中心 + 状态中心 + 会话档案馆 + 工具运行痕迹仓库”。
13. 当前实例的几个观察点
基于当前目录的实际内容,还能看出一些很有代表性的特征:
14. 如果你接下来想继续深入
推荐按这个顺序继续研究:
如果你愿意,这份文档之后还可以继续扩展成:
- “.codex 目录结构树完整版”
- “config.toml 字段逐项注释版”
- “会话 JSONL / SQLite 字段关系图”
- “如何安全迁移 .codex 到另一台机器”





