第一次在国内环境使用 Codex，目标不是把所有模型、插件和自动化都配好，而是完成一条能验收的链路：安装成功、登录方式明确、发送一条真实任务并知道请求走向。下面按这个顺序操作。
开始前：选择你要使用的入口
Codex 可以在桌面端、CLI 和 IDE 扩展中完成本地工作。本文以 CLI 为例；如果你偏好图形界面，安装和认证原则相同。先确认设备能访问官方安装与登录页面，企业电脑还需要遵守公司的网络与权限策略。
认证只选一条路线。ChatGPT 登录适合使用订阅或工作区权限的个人与团队；API Key 登录适合按 API 计费、脚本或 CI 等程序化场景。不要在还没确认路线前就手工改 auth.json。
两种认证方式的当前功能边界以 OpenAI 的Codex Authentication为准。
Windows：安装后先验证命令可用
在 PowerShell 中按照官方安装方式安装 Codex。安装完成后，关闭并重新打开一个终端，再运行 codex --version。能看到版本号，才说明系统已能找到该命令。
如果系统提示找不到 codex，先检查安装是否完成以及 npm 的全局可执行目录是否已进入 PATH；不要因为这个错误先重写认证或 Provider 配置。若 PowerShell 因公司策略限制脚本执行，请先确认策略来源。受组策略管理的设备不要绕过限制，应联系管理员。
macOS：区分安装完成与终端环境已刷新
在 macOS 安装 Codex 后，重新打开 Terminal，再运行 codex --version。若命令找不到，先检查 Node.js 与 npm 的安装结果，以及当前 shell 的 PATH。这里的排查和 API Key 无关，先把命令本身跑通。
安装后，先登录，不要先复制配置
使用官方 OpenAI 路线时，在 Codex 中选择 ChatGPT 登录或 API Key 登录。登录完成后，在当前客户端确认活跃账户或 API Key 状态。需要换路线时，先退出已保存的凭证，再重新登录；CLI、IDE 扩展和桌面端可能复用本地凭证缓存。
auth.json 不是普通配置示例：若系统采用文件式凭证存储，它可能包含可用的访问令牌。不要提交到 Git、发到群里，也不要为了“重置”而删除整个 ~/.codex 目录。
需要第三方模型时，再配置 Provider
只有当你确实要接入第三方模型或中转服务时，才进入 Provider 配置。请把 API Key、Provider、Endpoint 与模型 ID 看作四个独立字段：Key 证明调用权限；Provider 表示服务方；Endpoint 是实际请求地址；模型 ID 必须来自该 Provider 的当前列表。
机器级 Provider 与认证配置应放在用户级 ~/.codex/config.toml；项目内 .codex/config.toml 不适合承载这些机器级字段。官方配置参考也说明了项目级文件不能覆盖 Provider 和认证等关键项。
字段含义与适用范围请查官方 config.toml 配置参考，不要把不明来源的完整配置块直接粘贴进项目。
通过 AI Code With 配置时，使用当前文档
如果你选择 AI Code With 作为模型接入选项，请为这台设备或项目创建可单独撤销的 Key，并使用当前 Codex 文档所提供的配置片段。模型 ID、Endpoint 和支持范围都可能变化；旧文章中的地址不应视为当前配置。
从AI Code With 控制台创建和管理独立 Key。
随后按照AI Code With Codex（终端）配置文档填写 Provider、Endpoint 与模型；平台文档中的链接已统一使用 aicodewith.ai 域名。
用一次小任务验收
在一个不含敏感文件的空目录或测试项目中启动 Codex，给出一条小而可验证的任务，例如“只读取当前目录，列出文件并说明每个文件的用途”。成功标准不是只出现欢迎界面，而是任务得到正常响应；如使用第三方 Provider，还应能在其后台看到对应调用。
不要为了跳过权限提示而一开始就授予宽泛权限。先看 Codex 显示的文件范围和操作类型，再决定是否允许；测试任务完成后，检查是否产生了预期外的文件改动。
常见错误的最短排查路径
找不到 codex
这是安装或 PATH 问题。重新打开终端后执行 codex --version；确认 Node.js、npm 与全局安装结果，再处理登录。
401 Unauthorized
先检查当前认证路线和 Key 归属：Key 是否完整、是否已失效、是否属于该 Provider，客户端是否仍在使用缓存的另一种凭证。401 不是让你修改 Endpoint 的信号。
404 Not Found 或 model not found
404 优先核对 Endpoint、路径和协议；model not found 则核对当前 Provider 提供的精确模型 ID。两者都不要靠随机修改 /v1 或模型显示名称来解决。
完成后该看哪篇
如果你已能启动 Codex、但需要处理 Key、Provider 和报错细节，请继续阅读Codex API Key 配置与排错指南。这篇文章保留“首次跑通”的边界，避免与专题配置页竞争同一搜索意图。
