Codex CLI 接入 8848API：从安装到项目使用
用自定义 Provider 连接 Responses 接口，安全加载令牌、合并 config.toml、选择可用模型，并从只读项目任务开始检查审批、输出和用量。
更新：2026-10-15 · 菜单随客户端版本变化，以实际版本为准。模型权限、协议和价格以当前账户可用服务为准。
1. 准备：CLI不是普通聊天客户端
先登录控制台，在「令牌管理」创建单独用于此工具的令牌。检查有效期、额度、允许模型和访问限制；令牌不是网站登录密码，也不是厂商官方账号。
- 模型 ID：从当前账户可用列表复制完整名称，不用中文显示名或凭印象填写版本。列表可见不等于该模型支持每一种协议和工具功能。
- 预算：首次选一个已授权的模型，先进行一轮短对话。Agent 可能一项任务连续调用多轮；工具、附件、长历史和自动重试都会增加用量。
- 保护密钥：不要粘贴到聊天、截图、工单正文、公开项目或分享链接。日志和配置备份也按敏感文件保管。
- 已有配置：先用客户端自带导出/备份，或私下保存原配置，再合并新增条目；不要用教程整份覆盖已有服务商、MCP、项目或认证设置。
平台提供Responses路由，但仍需所选模型、令牌权限和渠道兼容。不要因为某模型在聊天客户端可用，就认为它适合Codex工具循环。
2. 安装并查看版本
选择一种官方安装方式即可，避免npm与系统包管理器同时装出多个codex。npm方式先按当前官方要求安装Node.js：
npm install -g @openai/codexmacOS已使用Homebrew的用户也可选：
brew install --cask codex安装后在准备实际工作的终端检查：
codex --versioncodex --helpWindows可在受支持的原生终端或WSL中按官方说明安装；WSL与Windows的用户目录、环境变量和安装位置是分开的，先决定在哪个环境使用，不混用配置。
安装或更新只影响客户端，不会自动创建平台令牌、开通模型或配置协议。官方发布包按系统/架构选择，不从搜索广告下载“免登录版”。
3. 在当前终端安全加载令牌
建议使用专用变量 API8848_KEY，避免与其他工具的OPENAI_API_KEY混淆。以下输入方式不把完整密钥写进命令历史；输入时不会显示明文。
macOS / Linux：bash或zsh
read -r -s API8848_KEYexport API8848_KEYWindows PowerShell
$secret = Read-Host "8848API Key" -AsSecureString$env:API8848_KEY = [System.Net.NetworkCredential]::new("", $secret).Password变量只对该终端及其之后启动的子进程有效。关闭终端、从桌面图标启动应用、使用另一个IDE或系统服务，都可能看不到它。需要长期使用时采用可信的系统密钥管理/环境配置方式；不要把密钥写进仓库或教程分享配置。
不要用打印变量的方式检查密钥。可参考 仅检查是否存在的诊断命令。
4. 合并配置，而不是覆盖整份文件
默认用户配置为 ~/.codex/config.toml；Windows的~表示当前用户目录。若设置了CODEX_HOME，以实际生效位置为准。先备份，保留已有MCP、审批、sandbox和项目设置，不复制他人的auth.json。
Provider及认证应写在用户级配置；当前官方文档说明项目级 .codex/config.toml中的Provider定义/选择不会作为该配置来源生效。不要把用户级Provider示例误贴进项目仓库。
将下面顶层字段合并到文件的顶层，将Provider表放在适当位置；不要把顶层字段粘贴到已有的其他TOML表下面：
model_provider = "api8848"
model = "REPLACE_WITH_AVAILABLE_MODEL_ID"
[model_providers.api8848]
name = "8848API"
base_url = "https://api.884819.xyz/v1"
env_key = "API8848_KEY"
wire_api = "responses"
requires_openai_auth = falseREPLACE_WITH_AVAILABLE_MODEL_ID必须替换为当前令牌可用且兼容Responses的完整ID，不能原样运行。model_provider与[model_providers.api8848]中的ID一致。base_url到/v1为止，不附加/responses，不重复/v1。env_key只存变量名，不是密钥本身。wire_api使用responses，不照搬旧chat配置。requires_openai_auth = false用于此平台令牌Provider；true会走官方认证并忽略env_key，不要混用。
如果已有同名Provider，编辑现有条目，不再添加重复表；检查启动profile是否另有选择。桌面应用可能共享用户配置，但并不共享当前终端的环境变量。
5. 先做一轮短验证
在你信任的测试Git项目目录，运行下面命令，保留默认安全与审批约束；不要添加跳过仓库检查或危险免审批参数：
codex exec "请只回复：连接成功。不要读取文件，不要调用工具。"- 确认没有缺少环境变量、模型不存在或协议错误。
- 在平台调用记录核对时间、模型和用量；请求成功不等于所有后续工具能力都可用。
- 若返回401/404等，先按 排障指南检查，不连续批量换模型重试。
不要在包含生产密钥的目录开展第一次测试；所谓“只输出OK”依旧是真实模型请求。
6. 正常使用：先读，再改，再检查
- 在可信项目目录启动
codex，只批准你知道来源的项目。先说明任务边界，例如“只解释结构，不修改文件、不联网”。 - 查看它准备读取的文件和拟执行的命令。修改代码时先保存当前工作，使用Git或本地备份保留回退点。
- 要求先说明拟改范围，再逐项检查diff、测试命令与结果。模型回复“已完成”不等于代码已经正确。
- Shell、安装依赖、网络访问与写文件属于工具能力，需要模型及服务端完整支持；逐项批准，不默认给整个电脑无限权限。
- 部署、发送消息、推送仓库和真实扣费请求应单独确认，不因本地代码编辑获准就顺带执行。
长会话会增加输入用量；一次任务可能包含多轮工具调用。及时结束已完成的任务，避免为验证连接让Agent扫描整个仓库。
7. 常见问题与恢复
提示env var missing
在同一终端重新加载变量；核对env_key拼写。不要把变量值贴出来。GUI启动的应用需单独确认环境，不用重装CLI来解决。
仍然进入官方登录/使用原模型
检查实际Provider、profile和配置来源；确保本Provider的requires_openai_auth不是true。保留原官方凭据，不通过删除auth.json来盲排。
短对话正常，工具/流式异常
核模型和渠道的Responses工具兼容性、SSE/连接错误与上下文限制。仅有模型列表和简短文字通过不足以验收编程Agent。
更换配置后要恢复
合并恢复原Provider选择或用备份恢复相关片段，保留期间新增的无关配置。不要清空全部Codex目录。
与手机远程有什么关系？
CLI自定义Provider不授予官方手机远程或云任务权益，见 远程能力说明。
官方资料与核验边界
本文整理安装与配置方法，不代表所有客户端版本、模型、工具调用或远程功能均已实测。本次文档更新未发起付费模型请求；文中的模型验证、首次对话和自动化运行可能计费，请确认模型与预算后自行执行。