codex-env-config · diff
git:20260711.dae29b8 to git:20261015.c21ad69
23 added, 133 removed. Audit A to A.
---
name: codex-env-config
- description: "记录、迁移和排查 Codex CLI 环境配置。适用于 Codex 安装升级、订阅制认证、代理注入、Homebrew、skills 同步及远端环境适配。"
+ description: "Codex 环境配置兼容入口：安装升级、环境迁移、运行配置、认证、代理、Responses WebSocket 与技能同步统一读取 codex-ops 对应能力及 operation。"
---
- # Codex 环境配置知识库
-
- 用于沉淀、迁移和排查 Codex CLI 的本机/远端环境配置，包括安装来源、订阅制认证、代理注入、Homebrew 更新、skills 同步和远端适配策略。
-
- ## 强制前置步骤
-
- 进入本 skill 后，第一件事必须读取同目录下的 `experience.local.md`：
-
- ```bash
- 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. 盘点当前环境
-
- 本机检查：
-
- ```bash
- command -v codex
- codex --version
- codex doctor
- ```
-
- 认证检查必须只输出结构化摘要，不输出密钥明文。可检查：
-
- - 认证文件是否存在。
- - `auth_mode` 是否为订阅制模式。
- - 是否存在 ChatGPT tokens。
- - 是否仍残留 API key 字段。
-
- ### 3. 安装或升级 Codex
-
- 优先使用 Homebrew cask 管理 Codex：
-
- ```bash
- brew install --cask codex
- brew upgrade --cask codex
- ```
-
- 如果发现旧的独立二进制：
-
- 1. 先确认 Homebrew 管理的 `codex` 可用。
- 2. 确认 `codex --version` 为预期版本。
- 3. 再清理旧二进制，避免 PATH 命中旧版本。
-
- ### 4. 配置代理注入
-
- Codex 代理应优先使用命令级注入，避免污染全局 shell：
-
- ```bash
- 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. 迁移到远端
-
- 远端迁移时按以下顺序处理：
-
- 1. 通过经验文件里的 SSH 入口连接远端。
- 2. 检查远端是否已有 Codex、Homebrew、shell 配置、认证文件。
- 3. 安装或升级 Homebrew cask Codex。
- 4. 复制订阅制认证文件，但不打印文件内容。
- 5. 为远端生成适配后的 `config.toml`。
- 6. 同步 skills 时解引用软链，避免远端出现断链。
- 7. 远端 hooks 默认保留，除非确认本机 hooks 引用的路径在远端也存在。
- 8. 运行 `codex doctor` 验证。
-
- 远端配置适配原则：
-
- - 本机 MCP server 中的本机绝对路径不能直接复制。
- - 本机 App 路径不能直接复制到远端。
- - 远端已有 hooks 且路径有效时优先保留。
- - 远端项目 trust path 要按远端真实目录生成。
+ # Codex 环境配置：兼容入口
- ### 6. 验证
+ 共享经验已归入独立 `codex-ops`；本入口保持原名称和触发范围。
- 完成后至少验证：
+ ## 路由
- ```bash
- command -v codex
- codex --version
- codex doctor
- ```
+ 1. 从当前技能目录或安装注册表定位并读取 `codex-ops/SKILL.md`，不能假设它位于本 Plugin 内。
+ 2. 按目标读取对应能力与 operation：
- 同时检查：
+ | 目标 | capability / operation |
+ | --- | --- |
+ | 安装升级、版本冲突 | installation / install-upgrade、diagnose-version-conflict |
+ | 远端环境适配 | installation / migrate-environment |
+ | 配置、全局指令、配置未生效 | configuration 下对应操作 |
+ | 技能安装同步与发现 | skills / install-sync、diagnose-discovery |
+ | 认证、代理、Responses WebSocket | connectivity 下对应诊断操作 |
- - Codex 来自预期安装来源。
- - 认证模式为预期模式。
- - 代理环境在 Codex 执行时存在。
- - WebSocket 或 ChatGPT/OpenAI 连接可达。
- - 旧版本二进制没有继续被 PATH 命中。
+ 3. 本机旧记录已迁移时，`experience.local.md` 仅提供新源与历史入口；其他安装若仍保留旧文件，将其视为带日期的历史，不先把整份记录当成当前配置。
+ 4. 完成、失败或中断后按 Codex OPS 写回唯一归属；当前规则、版本和设备身份优先于旧记录。
- ### 7. 经验沉淀
+ ## 安装与依赖缺失
- 每次完成配置或排障后，把已验证事实追加到 `experience.local.md`：
+ 通过 knowledge-base Plugin 单独安装此入口时，同时安装仓库中的独立 `harness/codex-ops`；全量安装器已包含 harness。依赖缺失时明确说明，按当前授权安装或继续不受影响的只读盘点，不凭记忆复刻旧操作。
+ 安装 Agent 读取 Codex OPS 的全局前置提示词；只有确认规则和目标范围后才写全局，不把正常安装授权等同于修改全局。
- - 日期。
- - 操作目标。
- - 当前安装路径和版本。
- - 认证模式摘要。
- - 代理和镜像配置。
- - 成功/失败命令的关键结论。
- - 后续再次执行时必须避开的坑。
+ ## 保留边界
- 只写已经验证过的事实，不写猜测。
+ - 只读取必要认证摘要，不打印或记录秘密。
+ - 目标机器、安装来源、配置根、hooks/MCP/代理和凭据存储必须按当前环境适配。
+ - HTTP-only 的条件、传输层区分、恢复与实际请求验证在 connectivity/diagnose-websocket 维护；旧私有后端 URL 不作为通用配置。
+ - 查询脚本和额度字段解释继续由 `codex-quota` 维护。