# 用自己的 Key 接入 Codex 桌面客户端

推荐流程面向 Windows／macOS 上已安装的 **Codex 桌面程序**。在本机隐藏输入一次本站 Key，工具自动配置默认文字模型和用户级生图 Skill。完成后重新打开桌面程序即可使用，不需要以后从终端启动。

WorkBuddy 只负责识别环境、下载校验和准备命令，不改变 WorkBuddy 自身的聊天连接。请先识别实际操作系统，不沿用另一台电脑的路径。只需要图片工具、不改变 Codex 聊天连接时，使用[图片安装说明](https://api.muskloveai.com/skills/references/image.md)。

## 助手准备，客户只运行一条命令

1. 检查已安装的 Codex 桌面程序，以及包含 npm 的 Node.js 22.13+。按照[统一接入指南](https://api.muskloveai.com/SKILL.md)下载并校验固定版本 `1.3.3` 的 `setup.mjs`。
2. 将下面占位路径换成本机真实绝对路径，交付完整一条命令。客户先保存工作并完全退出 Codex 桌面程序，再在系统终端执行，避免运行中的应用覆盖配置；WorkBuddy 可以继续负责安装。Windows PowerShell 保留 `&`：

   ```powershell
   & "<Node 可执行文件的真实绝对路径>" "<已校验 setup.mjs 的真实绝对路径>" connect --client codex-desktop
   ```

   macOS 使用两个相同含义的真实路径，去掉 `&`。客户手动打开“终端”并粘贴命令；不生成 `.command` 文件，也不通过 `open`／AppleScript 代开终端文稿。不要假设 WorkBuddy 的隔离环境和客户终端能访问相同文件。
3. 在终端隐藏输入自己的本站 Key。不要把 Key 发到聊天、命令参数或日志中。请在安装前完整退出并在配置完成后重新打开 Codex 桌面客户端，再新建对话；安装器不会替客户强制结束进程。

桌面流程不支持 `--start`，不安装或启动另一套 npm Codex CLI，不强制结束正在运行的桌面程序。模型聊天和生图请求按客户本站账号价格消费；安装与只读检查不提交生成请求。

## 配置实际改在哪里

工具自动发现桌面程序及其自带引擎，读取该引擎的模型目录，与 Key 的可用模型取交集后选择推荐默认值；找不到匹配的推荐模型会明确停止，不随意套用某个 CLI 版本的模型元数据。

默认桌面配置通常位于 Windows 的 `%USERPROFILE%\.codex` 或 macOS 的 `~/.codex`，其中包含 `config.toml` 和 `auth.json`。工具会先备份，再合并本站设置，保留无关设置，图片 Skill 安装在选定配置目录的 `skills/allinai-image`。自定义 `CODEX_HOME`、多套桌面程序或多个候选需要确认实际目标，可显式传 `--codex-home <绝对目录>`、`--app-engine <绝对路径>`；以安装输出的实际路径为准。

安装流程还会注册本站本地图片工具（stdio MCP），只提供图片检查、生成和编辑能力；由 Codex 桌面程序自动启动，Skill 负责引导使用。工具直接读取同一份桌面配置中的本站凭据，不再让客户输入第二次 Key，也不需要另开服务。Key 保存在本机受目录权限保护的认证文件中，不在 Skill 或安装包中；文件权限保护不是钥匙串加密。配置不会替客户改变本站 Key 的分组、价格或优先级。

新版还会安装 `skills/allinai-social` 社媒助手，复用同一份经验证的本站 Key。社媒助手查询实时目录、按用户指定的数据总预算采集，并整理带来源的报告；它通过本站接口工作，不需要 Browser 或 Computer Use。`--without-social` 与 `--without-image` 可以分别跳过对应组件。安装不改变 Key 权限，未开通“社媒数据”分组时仍需用户在密钥管理中配置。数据查询费与模型分析费分开计算。

图片权限不足会报告“生图权限待配置”；文字权限、图片权限和本地工具执行检查分别给出结果。模型列表有图片模型，不代表真实生图已经成功。Windows 沙箱初始化失败也不能通过重输 Key 解决，更不能关闭沙箱或删除无关用户文件来隐藏问题。

## 后续使用、检查与恢复

以后直接打开 **Codex 桌面客户端**，在新对话中提出生图或改图要求。安装器不需要常驻，不要求使用私有 CLI 启动器；原有的 CLI 独立配置不会自动变成桌面配置。

需要排查时，由助手用已校验工具执行 `check --client codex-desktop` 或 `doctor --client codex-desktop`。check 检查配置与模型目录权限，doctor 进一步检查实际桌面引擎的本地工具环境；两者不提交收费生成请求。需要撤回接入时使用 `restore --client codex-desktop` 恢复备份，自定义目标继续使用相同的 `--codex-home`，随后重新打开桌面程序。

如果旧版安装在中途关闭后持续提示“另一个操作正在运行”，使用同一工具的 `repair --client codex-desktop`。先完全退出桌面和其他安装程序，在系统终端按提示确认；repair 不读取新 Key、不发送生成请求。多个旧备份需按工具输出选择完整 `--backup-id`，外部改动冲突时保留文件并停止，不能直接删除锁或盲目覆盖。新版中断写入会在下一次配置操作前自动恢复；修复结束后按报告重新接入。

macOS 的“Sandbox 不允许在终端中打开文稿”说明安装助手打开 `.command` 的方式被宿主阻止。让用户手动打开终端、执行已校验的直接命令即可处理这一入口问题；它本身不说明 Key、余额或模型接口故障，也不需要关闭系统安全设置。

## 显式 CLI 接入

仅当用户明确要独立 Codex CLI 时，把安装命令的客户端参数改为 `--client codex`。该路径保留原有 `~/.all-in-ai/codex-setup` 私有快照和 `~/.all-in-ai-runtime/codex-setup` 运行目录，输出专用启动器；CLI 可用 `--start` 请求立即启动，或省略它只配置，后续用启动器的 `start`、`check`、`restore`、`setup --advanced`。

桌面端与 CLI 的检查结果分别报告。未发送收费生成请求时，不宣称完整回复、工具调用或真实生图已通过；需要实测时再按用户授权执行。

维护依据：[Codex 网关接入](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)、[Codex 配置](https://learn.chatgpt.com/docs/config-file/config-reference)。本站 API 地址为 `https://api.muskloveai.com/v1`。