| name | codex-env-config |
| description | 记录、迁移和排查 Codex CLI 环境配置。适用于 Codex 安装升级、订阅制认证、代理注入、Homebrew、skills 同步及远端环境适配。 |
Codex 环境配置知识库
用于沉淀、迁移和排查 Codex CLI 的本机/远端环境配置，包括安装来源、订阅制认证、代理注入、Homebrew 更新、skills 同步和远端适配策略。
强制前置步骤
进入本 skill 后，第一件事必须读取同目录下的 experience.local.md：
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd 2>/dev/null || pwd)"
test -f "$SKILL_DIR/experience.local.md" && sed -n '1,220p' "$SKILL_DIR/experience.local.md"
如果当前执行环境无法可靠解析 SKILL_DIR，从本 skill 目录直接读取 experience.local.md。该文件是本地经验文件，允许包含真实路径、主机别名、代理端口、密钥文件位置和已验证事实。
边界
SKILL.md 只记录可分享的通用流程，不写真实用户名、绝对路径、IP、端口、token 或 API key。- 真实环境值必须写入
experience.local.md，并确保该文件被 .gitignore 忽略。
- 不在聊天回复、日志或命令输出里打印 token、refresh token、session key、API key 明文。
- 需要同步认证时，只复制认证文件或使用官方登录流程，不展开其中的密钥内容。
- 远端环境不能盲目照抄本机配置，尤其是 MCP server、hooks、绝对路径和 App 路径。
使用场景
当用户提出以下需求时使用本 skill：
- 记录或复原 Codex CLI 环境配置。
- 将本机 Codex 订阅制配置迁移到远端机器。
- 排查 Codex 连接慢、升级失败、旧版本残留、代理未生效。
- 沉淀 Codex 的 Homebrew、Shell alias/function、认证模式、skills 同步经验。
标准工作流
1. 读取经验
先读取 experience.local.md，确认当前已验证的本机和远端事实：
- Codex 安装方式和真实二进制路径。
- 当前认证模式，是订阅制还是 API key。
- 代理端口和注入方式。
- Homebrew 镜像配置。
- 远端 SSH 入口、远端路径、hooks 和 MCP 的适配要求。
2. 盘点当前环境
本机检查：
command -v codex
codex --version
codex doctor
认证检查必须只输出结构化摘要，不输出密钥明文。可检查：
- 认证文件是否存在。
auth_mode 是否为订阅制模式。- 是否存在 ChatGPT tokens。
- 是否仍残留 API key 字段。
3. 安装或升级 Codex
优先使用 Homebrew cask 管理 Codex：
brew install --cask codex
brew upgrade --cask codex
如果发现旧的独立二进制：
- 先确认 Homebrew 管理的
codex 可用。
- 确认
codex --version 为预期版本。
- 再清理旧二进制，避免 PATH 命中旧版本。
4. 配置代理注入
Codex 代理应优先使用命令级注入，避免污染全局 shell：
codex_proxy_env() {
env HTTP_PROXY="$CODEX_HTTP_PROXY" HTTPS_PROXY="$CODEX_HTTPS_PROXY" ALL_PROXY="$CODEX_ALL_PROXY" "$@"
}
codex() { codex_proxy_env command codex "$@"; }
真实代理地址从 experience.local.md 读取，不写入本文件。
5. 迁移到远端
远端迁移时按以下顺序处理：
- 通过经验文件里的 SSH 入口连接远端。
- 检查远端是否已有 Codex、Homebrew、shell 配置、认证文件。
- 安装或升级 Homebrew cask Codex。
- 复制订阅制认证文件，但不打印文件内容。
- 为远端生成适配后的
config.toml。
- 同步 skills 时解引用软链，避免远端出现断链。
- 远端 hooks 默认保留，除非确认本机 hooks 引用的路径在远端也存在。
- 运行
codex doctor 验证。
远端配置适配原则：
- 本机 MCP server 中的本机绝对路径不能直接复制。
- 本机 App 路径不能直接复制到远端。
- 远端已有 hooks 且路径有效时优先保留。
- 远端项目 trust path 要按远端真实目录生成。
6. 验证
完成后至少验证：
command -v codex
codex --version
codex doctor
同时检查：
- Codex 来自预期安装来源。
- 认证模式为预期模式。
- 代理环境在 Codex 执行时存在。
- WebSocket 或 ChatGPT/OpenAI 连接可达。
- 旧版本二进制没有继续被 PATH 命中。
7. 经验沉淀
每次完成配置或排障后，把已验证事实追加到 experience.local.md：
- 日期。
- 操作目标。
- 当前安装路径和版本。
- 认证模式摘要。
- 代理和镜像配置。
- 成功/失败命令的关键结论。
- 后续再次执行时必须避开的坑。
只写已经验证过的事实，不写猜测。
