如果你是个程序员2026年还没认真用过Codex那你大概率还停留在“自己人肉翻报错、手动改代码”的开发方式里。Codex是OpenAI官方的AI编程工具但它跟你在网页里聊天的那种AI完全不是一回事——它更像一个能住进你终端里的AI实习生能读你的仓库代码、能执行命令、能跑测试把一个含糊的需求变成真实的改动。这篇教程面向所有第一次接触Codex、或者装了但一直跑不顺的人覆盖从下载安装、登录认证、核心配置到接入DeepSeek这类第三方模型再到常见报错的完整流程。我尽量把每一步都写到“照着做就能成功”的程度也会把踩过的坑一并交代清楚。1. 先搞明白你要装的Codex到底是哪个1.1 CLI、桌面版和IDE插件的区别现在“Codex”这个词至少指三种东西很多新手就是在这里被绕晕的形态是什么适合谁Codex CLI终端里运行的开源命令行工具核心形态开发者、喜欢命令行、要做自动化流程的人Codex桌面版带图形界面的客户端针对macOS和Windows不习惯命令行的用户、想可视化操作的人IDE插件装在VSCode/JetBrains等编辑器里的扩展想在编辑器里直接对话和改代码的人三种形态底层用的是同一套Codex引擎但命令行CLI是功能最完整、可控性最高的形态。很多第三方配置工具比如后面要讲的CC Switch也是围绕CLI的配置体系来做的。所以我强烈建议不管最后用不用桌面版先把CLI装好、把配置跑通这是最省事的学习路径。1.2 为什么推荐从CLI入手CLI的好处很朴素跨平台一致、依赖少、安装包小而且它天然适合“脚本化”——你可以用一条命令把Codex嵌进自己的CI流程或自动化脚本里。桌面版固然好看但版本更新往往比CLI慢半拍出问题时的报错信息也没有CLI那么直白。另外一个很实际的点是Codex CLI的安装包在GitHub上开源发布安装和使用的核心逻辑不依赖某个封闭生态。这意味着你可以自由切换模型供应商比如接入DeepSeek、通义这类国内平台。CLI是自由度和可玩性最高的一条路。1.3 关于版本和来源的提醒以2026年初的最新版为准Codex CLI在GitHub上的release页面会同时提供Windows、macOS、Linux三种平台的包。安装时务必认准官方仓库或官方安装脚本不要从乱七八糟的网盘下载来路不明的“破解版”。这里多说一句Codex CLI本身是免费开源的真正的付费点是模型调用额度官方订阅或API按量付费都行。凡是要你花钱买“破解版安装包”的都是利用信息差收智商税没必要碰。2. 下载与安装全流程2.1 获取安装包的几个渠道最正统的方式是去GitHub官方仓库的releases页面下载对应平台的压缩包。如果你所在网络环境下GitHub下载速度比较慢可以用一些合规的开源软件加速镜像站来下载release文件或者用npm、Homebrew这类包管理器直接安装效果一样。对于macOS用户最简单的方式是Homebrewbrew install codex如果brew里还没有这个tap先添加官方tapbrew tap openai/codex brew install openai/codex/codexWindows和Linux用户建议直接下载releases里的二进制包然后手动加入PATH这样最可控。2.2 Windows安装步骤第一步到GitHub release页面下载Windows版的zip压缩包文件名一般长这样codex-x.x.x-windows-x64.zip。第二步解压到一个干净目录。我习惯放在C:\codex路径里不要有中文和空格否则后面配置环境变量容易出幺蛾子。第三步把目录加入系统的PATH环境变量。打开“系统属性-环境变量”在用户变量的Path里新增一条C:\codex。如果不想开图形界面也可以用命令setx PATH %PATH%;C:\codex注意setx会影响当前用户后续打开的终端改完记得重开一个终端窗口。第四步如果你用的是Windows桌面版那直接下载exe安装包一路点下一步即可。首次启动会要求登录桌面版的配置其实还是读取CLI同一套配置所以下面的配置部分对桌面版一样有效。2.3 macOS安装与常见坑用brew安装最省心。装完之后在终端敲codex --version如果提示找不到命令通常是Apple Silicon机器上brew的安装路径没进PATH。检查一下~/.zshrc或~/.zprofile里有没有加export PATH/opt/homebrew/bin:$PATH然后执行source ~/.zshrc重载配置。另外macOS首次运行Codex时系统会弹“权限”确认框。这个要允许否则Codex无法访问你的工作目录和终端能力。2.4 Linux安装步骤Linux下同样推荐直接下载二进制包wget https://github.com/openai/codex/releases/download/版本/codex-版本-linux-x64.tar.gz tar -xzf codex-*.tar.gz sudo mv codex /usr/local/bin/然后验证codex --version装有npm的机器也可以用npm install -g openai/codex这种方式会自行处理PATH适合喜欢包管理的朋友。2.5 安装后的目录结构第一次运行codex时它会在用户主目录下创建.codex文件夹里面有config.toml、session、skills等目录。Windows上对应的是C:\Users\你的用户名\.codex。后续所有核心配置都在这里牢记这个路径。3. 登录认证与账号配置3.1 两种主流登录方式Codex登录方式基本分成两条线选择哪一种取决于你的使用场景方式适用账号适合场景缺点ChatGPT账号登录ChatGPT Plus/Pro/Team等订阅用户日常使用、体验官方模型部分模型仅限订阅权益不支持随意自定义模型名API Key方式OpenAI API平台用户按量付费、接入第三方模型需要自己管理密钥和额度如果只是个人开发、想赶紧用起来ChatGPT账号登录最方便。如果你打算给Codex接DeepSeek等第三方模型或者想精确控制模型和费用那就用API Key方式。3.2 ChatGPT账号登录详细流程在终端执行codex login它会打印出一个验证链接并自动打开浏览器。如果自动打开失败手动复制链接到浏览器。在页面上确认授权回到终端就会看到登录成功的提示。登录失败的几个典型情况浏览器长时间转圈等几秒再刷新不要反复发起新的login命令。提示codex auth token is unavailable这是登录态没拿到先执行codex logout再重新login。提示手机号或邮箱验证按页面提示正常完成即可这一步没法跳过是账号的安全机制。3.3 组织设置加载如果你的ChatGPT账号属于某个团队或组织登录后Codex会尝试加载组织设置。有些朋友遇到“无法加载组织设置”的报错这种情况大概率是登录态过期了重新执行一次login或者在账号后台确认你对这个组织有权限。3.4 API Key方式配置先去OpenAI API平台创建一个API Key然后写入环境变量export OPENAI_API_KEYsk-你的密钥Windows终端就是set OPENAI_API_KEYsk-你的密钥为了开机自动生效建议把export OPENAI_API_KEY...写进~/.zshrc或~/.bashrcWindows则用“系统属性-环境变量”里新增用户变量。3.5 国内用户使用建议Codex CLI本体是开源工具安装和运行没有限制官方流程直接走就可以。日常使用如果觉得官方服务的网络连接有波动一个很实用的方案是把模型供应商切换到国内大模型平台比如DeepSeek用官方兼容接口接入体验会顺畅很多。这部分在第五章详细讲。4. 核心配置文件详解4.1 config.toml的位置与作用Codex的配置核心是一个TOML文件Linux/macOS~/.codex/config.tomlWindowsC:\Users\你的用户名\.codex\config.toml它控制三件大事用哪个模型、怎么调用、在什么权限下干活。学会改这个文件Codex的可玩性会直接上升一个档次。4.2 一个最基础的配置示例model gpt-5.4-codex model_provider openai sandbox_mode workspace-write approval_policy on-request逐行解释model默认使用的模型名必须是当前账号支持的名称。model_provider模型来源内置的有openai、chatgpt也可以自己定义。sandbox_mode沙盒权限等级。read-only只读workspace-write允许修改工作区文件danger-full-access不做限制慎用。approval_policy命令审批策略。on-request表示遇到高风险或耗时命令时先征求你的同意推荐新手用这个。如果你希望免打扰把approval_policy改成never但风险也对应上升。我的建议是初期不要图省事所有自动执行操作都要过目。4.3 新手最容易踩的配置坑热搜里有一条典型的报错codex is ignoring 1 unrecognized configuration setting. check for typos or d...翻译过来就是“配置里有不认识的参数检查拼写”。我在群里见过太多人把sandbox_mode写成sandboxmodel把approval_policy拼错还有人把网上抄来的旧版参数硬塞进来。解法很简单打开配置文件逐个核对不确定就删掉那行让Codex用默认值。4.4 自定义Skills目录新版Codex支持在~/.codex/skills下存放“技能”文件每个技能用Markdown描述专门给Codex提供领域知识或固定流程。比如你可以写一个“代码审查规范”技能每次提审时就让它自动按规范过一遍。初学阶段可以跳过这部分但等你用完一两个星期建议把高频使用的提示词沉淀成技能文件省下大量重复沟通成本。5. 接入DeepSeek等第三方模型5.1 为什么能把DeepSeek接进CodexCodex CLI本身并不绑定死某个模型它兼容“OpenAI API风格”的接口协议。DeepSeek提供了完全兼容的官方API所以只要在config.toml里把模型供应商指向DeepSeek的接口地址再配上DeepSeek的API Key就能让Codex底层跑DeepSeek的模型。这对国内用户特别实用你不需要关心任何网络通道问题直接走DeepSeek官方域名速度、稳定性都非常可靠。这也是“Codex接入DeepSeek”这个需求在开发者社区里火起来的原因。5.2 修改config.toml接入DeepSeek先把下面的内容写进~/.codex/config.tomlmodel deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat解析一下配置含义model指定默认模型为deepseek-chat这是DeepSeek对话模型。base_urlDeepSeek官方API兼容地址一定要带/v1。env_key告诉Codex去读取名为DEEPSEEK_API_KEY的环境变量来获取密钥。wire_api协议类型填chat对应OpenAI的Chat Completions接口格式。然后设置环境变量export DEEPSEEK_API_KEYsk-你的DeepSeek密钥最后启动Codex敲一个简单任务验证比如“读取当前目录里的README用中文写一段总结”。如果正常返回说明DeepSeek已经成功接入。5.3 用CC Switch管理多套配置当你需要在官方模型和多个第三方模型之间频繁切换时手工改config.toml就有点烦了。社区里有个很受欢迎的开源工具叫CC Switch它本质是一个图形化配置管理面板帮你维护多套config.toml方案一键切换。有些朋友用CC Switch时报过一句“CC Switch本地服务启动失败”之类的错误古早版本还出现过比较隐蔽的本地转发端口问题。排查思路很直接先看系统托盘里CC Switch的后台服务有没有起来再检查它要占用的本地端口是否被其他程序占用。实在不行就退出CC Switch重新启动或者重装到最新版。这类问题基本都是工具本身的本地服务没跑起来不影响已经写好的配置。5.4 “模型不支持”报错到底怎么回事热搜里有一条很有代表性的报错信息the gpt-5.6-sol model is not supported when using codex with a chatgpt account这个报错的意思是你用的是ChatGPT订阅账号登录但配置文件里指定的模型名gpt-5.6-sol不在这个账号的模型权益范围内。它可能来自某篇过时文章、某个网友分享的配置甚至是你自己手滑填错的模型名。解决办法看你的账号类型ChatGPT订阅账号把model改成订阅包含的Codex模型比如gpt-5.4-codex用官方ChatGPT默认配置最稳妥。API Key账号可以自由指定API侧支持的模型只要名称存在即可。用了第三方provider确认model名必须是该平台真实提供的模型ID比如deepseek-chat。这类问题通用的排查顺序是先看账号类型再看model名是否真实存在最后看provider配置是否匹配。不要盲目从网上抄一个模型名就填进去。6. 基础实战工作流6.1 让Codex在真实仓库里干活装好、配好之后真正的工作流很简单。进入你的项目目录cd /path/to/your/project codex启动后你会进入一个交互式对话界面。这时你可以提需求比如帮我分析一下最近几次commit看看有没有明显问题。Codex会自己读取仓库状态、查看文件、执行git命令然后把结论告诉你。如果它觉得需要改代码会在获得你同意后动手修改。相比网页版AICodex的核心优势是“它真的看得见你的项目”而不是靠你贴代码片段。6.2 审批策略的设置思路我建议新手用前面配置示例里的approval_policy on-request。这样Codex每次要跑命令前都会问你“是否允许执行”比如git push、rm -rf、npm install这类有副作用的操作都会被你看到。等到你对Codex的行为模式足够熟悉了再按需放宽到自动执行。记住一个原则AI会犯错审批是最后一道防线。6.3 多会话管理Codex默认会把历史会话保存在.codex/session目录下。中断后重新执行codex可以选择恢复之前的会话继续聊而不是从头再来。这个功能在处理长任务时特别有用比如排查一个跨多文件的bug你不想每次重新描述前因后果。如果你要在一个新终端里快速执行一次性任务新版Codex也支持非交互模式直接把任务作为参数传进去适合写脚本自动化。6.4 给生产环境的建议跑通之后我强烈建议按这个顺序推进先在一个不重要的测试仓库里试一两个星期摸清它的行为习惯。再把它用到真实项目里但只让它在分支上干活不要直接让它动主分支。生产环境的API Key务必通过环境变量注入不要写进任何会被提交的代码或配置文件里。7. 高频报错排查速查表最后把这些年社区里最高频的报错整理成一张速查表遇到问题直接对号入座。报错信息常见原因解决办法error: start the windows daemon from a non-elevated terminal; shared...在管理员权限的终端里启动Codex它不认这种环境关掉管理员终端用普通终端重新启动Codexcodex auth token is unavailable登录令牌没拿到或已过期执行codex logout后重新codex logincodex无法加载组织设置登录态过期或当前账号不属于该组织重新登录并在账号后台确认组织权限CC Switch本地服务启动失败工具内置的本地转发端口被占用或服务被系统拦截检查托盘服务、释放端口、重启工具或重装the gpt-5.6-sol model is not supported...模型名与账号类型不匹配改成账号支持的模型名或换API Key/第三方providercodex is ignoring 1 unrecognized configuration settingconfig.toml里有拼写错误或过时参数逐个核对配置项删掉不认识的参数显示更新agent沙盒/正在重新连接网络波动或后台同步未完成等待几秒后重试必要时重启终端安装卡死没有反应下载源速度太慢换镜像源下载release包或用包管理器安装codex登录不上多因账号验证未完成按官方流程完成邮箱/手机验证确认账号状态7.1 关于Windows daemon报错的补充上面第一个报错我在Windows上遇到过好几次特点是你用管理员身份打开PowerShell或CMD然后启动Codex它就报start the windows daemon from a non-elevated terminal。原因是Codex的Windows后台守护进程明确拒绝在提权环境下工作。这个设计是为了避免权限混淆。解法就是你换成一个普通权限的终端窗口。但如果你的项目本身需要管理员权限那先把项目和终端权限问题分开处理不要用提权来包治百病。7.2 登录类问题的通用处理所有和登录、token、组织设置相关的报错我总结出一套万能处理流程执行codex logout清掉旧状态。检查环境变量里有没有残留的OPENAI_API_KEY如果有且是旧的先清掉或更新。重新codex login按浏览器提示完成授权。如果还不行重启终端和Codex再试一次。90%的登录类问题都能靠这套组合拳解决。7.3 配置类问题的通用处理如果报错里带了unrecognized configuration setting或者check for typos不要慌这是Codex在好心提醒你。最蠢的做法是在论坛里复制别人的报错截图问“怎么办”最聪明的做法是打开config.toml。一眼扫过去看有没有拼写不对的键名。不确定的键直接注释掉重启Codex看效果。如果你抄的配置来自某个教程优先去官方文档核对键名。这套流程我每次都会先做通常在五分钟内解决。我个人在实际操作中的体会是Codex的配置和学习成本不算低但一旦跑通它带来的效率提升是实打实的——我平时的报错排查、跨文件重构、测试补写现在有一大半都交给它打底我再做复查和兜底。如果你也准备上手我的建议是先不折腾花活用官方默认模型把整个流程跑顺再去接DeepSeek、再去自定义Skills目录。踩过几次坑之后最后再分享一个小技巧把所有模型密钥都通过环境变量管理不要写死在config.toml里这样以后换模型、换电脑只需要带一个配置文件和环境变量清单就走比什么都省心。