欢迎光临
我们一直在努力

Codex 目录结构与配置说明详解

Codex 目录结构与配置说明详解

这份文档基于当前目录 C:\\Users\\用户名\\.codex 的实际内容整理,目标是帮助使用者从“能看懂目录”进一步走到“能理解 Codex 的运行机制、能力加载方式、会话持久化方式,以及哪些配置可以改、哪些文件最好不要手改”。 在这里插入图片描述

codex客户端下载:https://codexdown.cn/

1. 先看整体:.codex 是什么

.codex 可以理解为 Codex Desktop/CLI 的“本地工作中枢”。它通常承担下面几类职责:

  • 保存全局配置,比如默认模型、模型供应商、MCP Server、项目信任级别。
  • 保存认证信息和本地状态,比如 API Key、窗口状态、最近工作区。
  • 保存会话索引、对话回放、任务目标、日志、自动化任务等运行数据。
  • 缓存技能、插件、浏览器集成、图片生成结果、临时文件等扩展能力。
  • 存放与沙箱、浏览器控制、Node REPL、Computer Use 相关的运行时元数据。
  • 可以把它想象成下面这条链路:

    #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/
  • skills/find-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,可以按下面这条思路记忆:

  • config.toml 决定 Codex 用谁做模型、接哪些工具、信任哪些项目。
  • AGENTS.md 决定代理在当前环境里怎么表现。
  • skills/、plugins/、vendor_imports/ 共同组成能力扩展层。
  • browser/、computer-use/、node_repl/、MCP 配置共同组成工具执行层。
  • session_index.jsonl、sessions/、几个 sqlite 数据库共同组成持久化层。
  • generated_images/、ambient-suggestions/、cache/、.tmp/ 这类目录组成缓存与产物层。
  • 一句话概括:

    .codex 不是简单的配置目录,而是 Codex 在本地的“配置中心 + 扩展中心 + 状态中心 + 会话档案馆 + 工具运行痕迹仓库”。

    13. 当前实例的几个观察点

    基于当前目录的实际内容,还能看出一些很有代表性的特征:

  • 当前默认模型链路已经不是单一 OpenAI 配置,而是支持多 provider 切换。
  • 当前环境已经接入 MCP Server,说明这个 Codex 已经具备浏览器操作、Node 执行、Pascal 编辑等扩展能力。
  • 当前环境存在插件缓存和技能导入缓存,说明它不是“只会聊天”的纯净实例,而是已经演化为一套可扩展代理工作台。
  • 当前已经累积了较多会话历史和自动化基础设施,说明 .codex 更适合被当作长期运行的用户配置主目录,而不是一次性临时目录。
  • 14. 如果你接下来想继续深入

    推荐按这个顺序继续研究:

  • 先读 config.toml,理解 provider、MCP、project trust。
  • 再读 skills/.system/*/SKILL.md,理解技能如何被组织。
  • 看 plugins/cache/*/.codex-plugin/plugin.json,理解插件如何打包技能。
  • 看 session_index.jsonl 与 sessions/YYYY/MM/DD/*.jsonl,理解历史线程如何索引与归档。
  • 最后再看几个 sqlite 库的表结构,理解 Codex 如何把“线程、目标、自动化、日志”做成可恢复的本地状态。

  • 如果你愿意,这份文档之后还可以继续扩展成:

    • “.codex 目录结构树完整版”
    • “config.toml 字段逐项注释版”
    • “会话 JSONL / SQLite 字段关系图”
    • “如何安全迁移 .codex 到另一台机器”
    赞(0)
    未经允许不得转载:171主机测评 » Codex 目录结构与配置说明详解
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址