Featured image of post Codex 的 CODEX_HOME 是什么？会影响哪些目录和行为
AI

Codex 的 CODEX_HOME 是什么？会影响哪些目录和行为

系统说明 Codex 的 CODEX_HOME 作用范围，重点解释它为什么不只是 skill 目录变量，还会影响配置、认证、AGENTS.md、日志、历史、状态数据库，以及什么情况下应该修改它。

-- 次浏览
-- 条评论

Codex 的 CODEX_HOME 是什么？会影响哪些目录和行为

很多人第一次接触 Codex 的 skills，会先注意到 ~/.codex/skills/。接着很自然就会问一句：如果把 skill 放进项目里，或者把 CODEX_HOME 改掉，Codex 会不会自动识别？

这个问题表面上看像在问 skills，实际上问的是另一层东西：Codex 的本地工作根目录到底是什么，它会影响哪些文件。

如果你还没看过三家工具对 skills 支持方式的横向对比，建议先读这篇：

先说结论

CODEX_HOME 不是一个“只改技能目录”的小开关，它更像是 Codex 的主数据目录。

如果不设置它，Codex 默认会把自己的很多运行数据放到：

1

~/.codex

如果你显式设置了：

1

CODEX_HOME=/path/to/somewhere

那 Codex 往往就会把 skills、配置、认证、全局 AGENTS.md、历史、日志、状态等内容都切到这个新目录下，而不是只移动其中某一项。

很多人真正踩坑的地方不是“skill 没生效”，而是：

  • 为什么之前的 skill 不见了
  • 为什么模型配置和 trust 配置像重新初始化了一样
  • 为什么历史和日志不连续了
  • 为什么好像又要重新登录
  • 为什么全局 AGENTS.md 的规则也跟着变了

如果你只想快速判断是否该改 CODEX_HOME，可以先看这几条：

  • 如果你的目标只是“把 skill 放进项目里并让 Codex 识别”，通常不建议先动 CODEX_HOME
  • 如果你的目标是“切换一整套独立的 Codex 环境”，那才适合用 CODEX_HOME
  • 如果你的目标是“同一台电脑切多套 Codex 账号、API Key 或全局 AGENTS.md”，CODEX_HOME 就很适合
  • 对大多数已经稳定使用 ~/.codex 的用户来说，CODEX_HOME 更像“环境隔离工具”，而不是“skills 管理工具”

默认情况下，Codex 在哪里存东西

如果只讲“默认值”，那就是：

1

~/.codex

在默认情况下，这个目录里通常会集中存放：

  • config.toml
  • auth.json
  • history.jsonl
  • log/
  • logs_*.sqlite
  • state_*.sqlite
  • shell_snapshots/
  • skills/

这几个目录和文件本身已经说明问题了：Codex 会把本地配置和运行状态集中放在同一个根目录里。

所以，CODEX_HOME 的真正影响范围，天然就不只是一项。

CODEX_HOME 到底会影响什么

1. Skills 自动发现目录

这是最容易观察到的一项。

Codex 内置的 skill 创建/安装工具说明得很明确：

  • skills 默认安装到 $CODEX_HOME/skills
  • 如果没有设置 CODEX_HOME，那就回退到 ~/.codex/skills

这也是为什么当前这台机器上的用户级 skill 实际落在：

1

~/.codex/skills/

换句话说，如果你改了 CODEX_HOME，最先变化的一定是 skill 自动发现目录。

2. 配置文件位置

你当前机器上的配置文件在：

1

~/.codex/config.toml

里面不仅有模型与 provider 配置，还有项目信任状态。

一旦 CODEX_HOME 换到别处，Codex 往往就会去新根目录下找新的 config.toml。

这意味着：

  • 原来的模型配置不会自动带过去
  • 原来的 trust level 不会自动带过去
  • 你会感觉像切到了一套新的 Codex 环境

3. 认证状态

当前这台机器的认证文件在：

1

~/.codex/auth.json

如果新 CODEX_HOME 下没有对应文件，Codex 很可能会把自己当作一个新环境。

这通常意味着：

  • 认证状态不共用
  • 有可能需要重新登录或重新读认证配置

这也是为什么如果你想在同一台电脑上切换多套 Codex 账号或多组 API Key，最直接的做法通常不是来回改一个 auth.json，而是直接切不同的 CODEX_HOME。

4. 历史、日志和状态数据库

当前目录里还存在：

  • history.jsonl
  • log/
  • logs_*.sqlite
  • state_*.sqlite
  • shell_snapshots/

这说明本地运行期状态同样挂在 ~/.codex 下面。

所以切换 CODEX_HOME 之后，通常还会带来这些变化：

  • 历史会话不连续
  • 本地日志不连续
  • 状态数据库是另一套
  • shell 快照也是另一套

从实际效果上看，这更像“换了一整个 Codex 用户目录”，而不是“换了一个技能目录”。

5. 用户全局 AGENTS.md

这也是很多人一开始没意识到，但在团队协作里非常关键的一项。

如果你使用默认环境，那么用户全局指令文件通常就在：

1

~/.codex/AGENTS.md

而当你像我现在这样切到：

1

CODEX_HOME=~/data/work/.codex codex

对应的全局指令文件就会一起切到：

1

~/data/work/.codex/AGENTS.md

这个变化的价值非常实际：

  • 个人环境可以保留自己的写作风格、偏好、实验规则
  • 公司环境可以维护公司项目通用的协作约束、文档索引、代码规范
  • 两边互不污染

如果你在同一台电脑上同时处理个人项目和公司项目，这通常比把所有规则都硬塞进 ~/.codex/AGENTS.md 更干净。

为什么很多人会误解 CODEX_HOME

因为最先暴露出来的问题，往往就是 skill。

例如：

  • 原来 ~/.codex/skills/ 里的 skill 能自动识别
  • 改了 CODEX_HOME 之后突然不见了

这时候很容易得出一个错误结论：

CODEX_HOME 就是 skills 目录变量

但从实际目录结构看，它显然不只是这个作用。

更准确的理解应该是：

CODEX_HOME 是 Codex 的本地根目录，而 skills/ 只是这个根目录下面的一个子目录。

这两个层级如果不分清，后面做项目隔离、skill 迁移或者环境切换时就很容易误判。

什么时候适合修改 CODEX_HOME

场景一：多环境隔离

这是最适合改 CODEX_HOME 的情况。

比如你想做下面这种彻底隔离：

  • 公司项目一套环境
  • 个人项目一套环境
  • 实验项目一套环境

这时候你可以分别准备：

1
2
3

~/data/codex-home/work
~/data/codex-home/personal
~/data/codex-home/lab

然后按场景切换。

我现在这台机器就是这种思路的一个实际变体：

1
2

codex
codexwork

其中 codexwork 的定义就是：

1

alias codexwork='CODEX_HOME=~/data/work/.codex codex'

这种做法的优点是：

  • skill、配置、日志、历史全部隔离
  • 可以隔离不同账号或不同 API Key
  • 可以隔离不同的全局 AGENTS.md
  • 不容易相互污染

它的代价也很明显：

  • 更重
  • 要维护多套配置
  • 很多东西需要重新初始化

场景二：多账号与全局规则隔离

这是我认为很多人会低估，但其实很有价值的场景。

如果你的公司项目都集中在：

1

~/data/work/

那你完全可以专门准备：

1

~/data/work/.codex/AGENTS.md

把公司通用约束放进去，例如：

  • 公司内部项目目录结构
  • 统一技术栈约定
  • 文档索引入口
  • 代码评审口径
  • Git 提交约定

然后通过：

1

alias codexwork='CODEX_HOME=~/data/work/.codex codex'

把这套规则只作用在公司环境里。

这样做的好处是：

  • 公司项目有一份稳定的“全局协作规则”
  • 个人项目不必被公司规则干扰
  • 你不需要在每个公司仓库里都重复写一遍相同背景

场景三：项目级完整隔离

比如你想直接这样启动：

1

CODEX_HOME=$PWD/.codex codex

这意味着你要的不是“项目级 skill 目录”，而是“项目级 Codex home”。

好处：

  • 项目里可以封装一套完整环境
  • 非常适合高度隔离或团队统一方案

坏处：

  • 不只是 skill 变了，认证、配置、状态、历史也都可能跟着变
  • 如果目标只是复用一套 skill，这种方案太重

什么时候不建议改 CODEX_HOME

1. 你只是想把 skill 放进项目里并版本控制

这是最典型的“没必要改”的场景。

如果你的目标只是：

  • 项目里保存一份 skill
  • Codex 还能自动发现并使用它

更稳的方式通常是：

  1. 项目里保留一份 skill 源目录
  2. ~/.codex/skills/ 里做软链接指向项目里的目录

例如：

1
2

~/data/github/iminling-pages/tools/codex-skills/hugo-easyimage-cover-publisher/
~/.codex/skills/hugo-easyimage-cover-publisher -> 项目里的 skill 目录

这样你能同时得到：

  • 项目内可版本控制
  • Codex 继续自动识别
  • 不影响现有配置、认证、trust、日志和历史

如果你已经在用多套 CODEX_HOME，这里还有一个很实用的折中方案：

  • 把不同环境的 config.toml、auth.json、history.jsonl、AGENTS.md 分开
  • 但把多个环境的 skills/ 指向同一份目录

我当前机器上的公司环境就是类似做法：~/data/work/.codex/skills 直接软链接到 ~/.codex/skills。

这能减少重复维护，又不会破坏环境隔离的主体目标。

如果把这个思路再说得更明确一点，其实可以直接采用下面这种结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

~/.codex/
├── auth.json
├── config.toml
├── AGENTS.md
└── skills/

~/data/work/.codex/
├── auth.json
├── config.toml
├── AGENTS.md
└── skills -> ~/.codex/skills

这套结构的实际含义是：

  • ~/.codex/skills 作为公共 skills 中心
  • 其他 CODEX_HOME 通过软链接复用这一套 skills
  • 但每个 CODEX_HOME 仍然保留自己的 AGENTS.md
  • 每个 CODEX_HOME 也保留自己的认证信息和配置

这样做我认为很不错，原因很简单：

  • 通用 skill 只维护一份
  • 多套 Codex 环境都能直接用
  • 公司规则和个人规则不会混在一起
  • 账号、Key、trust、历史也能继续各自独立

2. 你已经有一套稳定的全局配置

对已经在长期使用 ~/.codex 的用户来说，贸然修改 CODEX_HOME 的副作用通常比收益大。

因为你改掉的不是一个局部目录，而是一整套根目录逻辑。

实际案例：我现在怎么用 CODEX_HOME

按我现在这台机器的真实使用方式，已经不是“只有一个 ~/.codex”这么简单了。

当前同时存在两套 Codex home：

1
2

~/.codex
~/data/work/.codex

其中：

  • 个人环境继续保留 ~/.codex
  • 公司环境单独放在 ~/data/work/.codex
  • 直接执行 codex，默认走个人环境
  • 我在 ~/.bash_profile 里定义了一个快捷方式：
1

alias codexwork='CODEX_HOME=~/data/work/.codex codex'
  • 执行 codexwork 时，就会切到公司环境

这两套目录下目前都实际存在这些文件：

  • config.toml
  • auth.json
  • history.jsonl
  • log/
  • logs_*.sqlite
  • state_*.sqlite
  • shell_snapshots/
  • skills/

除此之外，公司环境里还额外维护了：

  • AGENTS.md

另外还有一个非常有代表性的细节：当前 ~/data/work/.codex/skills 并不是单独维护一份，而是软链接到 ~/.codex/skills。

这说明 CODEX_HOME 并不是“所有东西都必须完全复制一套”。

你完全可以：

  • 把账号、认证、配置、历史、全局 AGENTS.md 隔离开
  • 但把 skills/ 继续共享

如果结合这台机器的实际情况，我的建议会分成两层：

第一层，当前这套“双 CODEX_HOME”思路本身是合理的：

  • 用多套 CODEX_HOME 隔离账号、Key、配置和全局 AGENTS.md
  • 用快捷命令按场景切换

第二层，不要为了“看起来更独立”就把所有东西都复制一份：

  • 如果 skill 本身不涉及账号隔离，可以继续共享
  • 如果只是想让 skill 项目化，优先用“项目目录 + 软链接”
  • 没必要把“skills 共享”和“环境隔离”硬绑定成二选一

这比直接把所有项目都切成 CODEX_HOME=$PWD/.codex 更稳，也更容易维护。

换句话说：

  • 如果你要的是“技能项目化”，优先做软链接
  • 如果你要的是“账号 / Key / 全局规则隔离”，优先考虑多套 CODEX_HOME
  • 如果你既要隔离又不想重复维护 skill，可以做“隔离 home + 共享 skills”

这两个目标不要混成一个问题。

和 skills 支持那篇文章怎么配合看

如果你从 skills 对比文过来，最容易记住的一句话是：

  • skills 对比文回答的是：三家工具怎么支持 skills
  • 这篇 CODEX_HOME 文回答的是：Codex 本地环境为什么会把技能目录、配置和状态绑定在一起

前者是横向对比，后者是 Codex 的本地环境专题。

两篇配合起来，基本就能把这类问题讲透：

  • skill 到底该放哪
  • 为什么 Codex 常见目录是 ~/.codex/skills
  • 为什么只想迁移 skill 时，不一定应该先动 CODEX_HOME
  • 为什么一台电脑上多套账号或多套全局 AGENTS.md，反而很适合用 CODEX_HOME

总结

如果把 CODEX_HOME 只看成“skills 目录变量”，很容易做出错误决策。

更准确的理解是：

  • CODEX_HOME 是 Codex 的本地根目录
  • skills/ 只是这个根目录下的一部分
  • 一旦切换它，通常会连配置、认证、全局 AGENTS.md、历史、日志和状态一起切换

所以：

  • 想隔离一整套 Codex 环境，改 CODEX_HOME
  • 想在同一台电脑上切多套账号、API Key 或全局 AGENTS.md，也很适合改 CODEX_HOME
  • 只想把 skills 放进项目并继续自动发现，优先考虑“项目目录 + 软链接”而不是直接改 CODEX_HOME
  • 如果你既要隔离环境又不想重复维护 skill，可以让不同 CODEX_HOME 共享同一份 skills/

本文基于 2026 年 3 月 21 日的本机环境实测，以及当前可见的 Codex skill 工具链说明整理。后续如果 OpenAI 公开补充了更完整的本地目录发现文档，这部分结论也值得再更新一次。

参考资料：