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

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

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

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

Claude Code、Codex、OpenCode 对 Skills 的支持现状对比

写在前面

先给结论：

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

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

1
~/.codex

如果你显式设置了：

1
CODEX_HOME=/path/to/somewhere

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

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

为什么之前的 skill 不见了
为什么模型配置和 trust 配置像重新初始化了一样
为什么历史和日志不连续了
为什么好像又要重新登录

先说结论

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

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

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

就我当前这台机器的实际环境来看，系统里没有显式设置 CODEX_HOME。

因此，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 配置，还有项目信任状态，例如当前仓库的：

/Users/konghang/data/github/iminling-pages
在当前配置里是 trusted

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

这意味着：

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

3. 认证状态

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

1
~/.codex/auth.json

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

这通常意味着：

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

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

当前目录里还存在：

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

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

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

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

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

为什么很多人会误解 CODEX_HOME

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

例如：

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

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

CODEX_HOME 就是 skills 目录变量

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

更准确的理解应该是：

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

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

什么时候适合修改 CODEX_HOME

场景一：你要隔离一整套 Codex 环境

这是最适合改 CODEX_HOME 的情况。

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

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

这时候你可以分别准备：

1
2
3
~/data/codex-home/work
~/data/codex-home/personal
~/data/codex-home/lab

然后按场景切换。

这种做法的优点是：

skill、配置、日志、历史全部隔离
不容易相互污染

它的代价也很明显：

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

场景二：你想做项目级的完整 Codex 环境

比如你想直接这样启动：

1
CODEX_HOME=$PWD/.codex codex

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

好处：

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

坏处：

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

什么时候不建议改 CODEX_HOME

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

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

如果你的目标只是：

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

更稳的方式通常是：

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

例如：

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

这样你能同时得到：

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

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

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

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

对当前这台机器来说，我的建议是什么

如果只看这台机器的当前状态，我的建议非常明确：

不建议为了迁移 skill 而改 CODEX_HOME
更适合继续保留默认的 ~/.codex
如果要把某个 skill 放进项目仓库，就让项目目录成为“源目录”，再由 ~/.codex/skills/ 去引用它

这比直接把 CODEX_HOME 切到项目目录更稳，也更容易维护。

换句话说：

如果你要的是“技能项目化”，优先做软链接
如果你要的是“整套环境隔离”，再考虑 CODEX_HOME

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

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

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

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

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

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

skill 到底该放哪
为什么 Codex 常见目录是 ~/.codex/skills
为什么只想迁移 skill 时，不一定应该先动 CODEX_HOME

总结

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

更准确的理解是：

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

所以：

想隔离一整套 Codex 环境，改 CODEX_HOME
只想把 skills 放进项目并继续自动发现，优先考虑“项目目录 + 软链接”而不是直接改 CODEX_HOME

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

参考资料：