Codex 保姆级上手指南：从安装到接入国产模型与权限实践

AICODINGAGENT·上手指南Codex保姆级上手指南从Windows安装、接入国产模型到三档权限实践覆盖桌面版/CLI/IDE扩展·CCSwitch配置·DeepSeek与智谱GLM接入沙箱与审批策略·插件与技能生态·与ClaudeCode的取舍技术教程·2026年9月整理目录01认识Codex与安装VibeCoding背景·三种形态·Windows/CLI安装·登录02配置与接入国产模型.codex目录·CCSwitch·DeepSeek/GLM·config.toml03核心使用与权限Chat/Project·三档权限·沙箱·模型与推理档·插件技能04对比、风险与上手路线CodexvsClaudeCode·安全红线·FAQ·三阶段路线01·背景从"自动补全一行"到"Agent自己改完一个项目"代码补全Copilot时代：人写、AI补全单行或函数，不碰文件系统。对话式写代码ChatGPT时代：贴需求、拿代码片段，人自己复制粘贴回去。编程智能体Codex/ClaudeCode：读项目、改多文件、跑命令、自己测试。2025年2月，AndrejKarpathy提出"VibeCoding"：用自然语言描述意图，让LLM写代码，人通过运行结果而不是逐行阅读来验证。据YCombinator统计，其2025冬季批约25%的创业公司代码库中95%以上由AI生成；Codex正是这一代"编程智能体"的代表产品之一。来源：Karpathy2025.02公开发言；YCombinatorW25批次统计；Snyk、arXiv相关综述。01·市场拐点编程智能体已从尝鲜进入日常开发工具链88%组织已在工作中使用某种AI编程工具25%YCW25批次创业公司代码库95%+由AI生成Codex是OpenAI推出的编程智能体，独立产品线已整合进GPT主模型；它能理解项目代码、自动开发与测试、运行终端命令。与对话式工具相比，它的工作单元从"一段代码"变成了"一个任务"。开发者与终端里的AI智能体协作来源：StanfordAIIndex2025企业采用调查；YCombinatorW25批次公开数据。01·产品形态同一个Codex，有桌面App、命令行和IDE扩展三种用法形态适合谁特点本指南侧重桌面App新手、非终端用户图形界面，点选项目与权限，最友好本指南主讲CLI命令行习惯终端的开发者轻量、可脚本化、开源，支持自定义模型补充介绍IDE扩展VSCode日常用户在编辑器内直接唤起，与diff、调试联动点到为止桌面版与Windows原生CLI共用同一本地配置目录

%USERPROFILE%\.codex，改配置后两边都生效。01·认识与安装CHAPTERONE认识Codex与完成安装先弄清楚它能做什么，再用最短路径把桌面版装到Windows上登录、安装方式选择、常见报错一次说清0101·安装Windows桌面版：官网下载或一行winget命令方式A·官网图形安装（推荐新手）1打开官方CodexApp页面/codex/app2点击"下载Windows版"，得到安装包3双击安装包，按向导完成4开始菜单搜索Codex（现已并入ChatGPT）打开方式B·命令行安装打开PowerShell，执行：wingetinstallCodex-smsstore适合习惯命令行的用户；装完同样在开始菜单打开。后续可在应用商店自动更新。01·认识与安装01·CLI安装喜欢终端的人：三条命令装好CodexCLIWindowswingetinstallCodex#或用npm：npminstall-g@openai/codexcodex--versionmacOSbrewinstallcodex#或用npm：npminstall-g@openai/codexcodex--versionLinuxsudoaptinstallnodejsnpmsudonpmi-g@openai/codexcodex--version验证：安装成功后执行codex--version能打印版本号即可。新手优先独立安装包，依赖更少。01·认识与安装01·登录两种登录方式：ChatGPT账号，或直接填APIKey方式一·ChatGPT账号登录·打开Codex后自动跳转浏览器·用已有ChatGPT账号授权登录·走订阅额度（Plus/Pro/Team）·最省事，适合大多数个人用户方式二·APIKey·在OpenAI平台申请并复制Key·在Codex登录页选择APIKey模式·按token用量计费，与订阅分开·适合企业、需要接第三方网关的用户提示：没有ChatGPT账号时再用APIKey；接国产模型的配置方式见第二章。01·排错装完打不开？五个最常见的小问题现象处理方式开始菜单搜不到Codex它已并入ChatGPT，搜"ChatGPT"打开即可。winget提示找不到包确认命令带-smsstore，并升级winget到最新版。npm装完提示codex不是命令把npm全局bin目录加入系统PATH，重开终端后重试。登录跳转浏览器失败检查默认浏览器与网络代理；复制授权链接到浏览器手动打开。改完配置不生效完全退出Codex桌面版再重启，确保新配置被读取。01·认识与安装CHAPTERTWO配置与接入国产模型没有OpenAI官方Key也能用Codex：通过CCSwitch接DeepSeek、智谱GLM理解.codex配置目录，掌握BaseURL与config.toml0202·配置基础所有配置都在一个隐藏目录里：.codex~/.codex/├──auth.json#登录凭据/APIKey├──config.toml#模型与权限配置├──projects/#各项目信任设置└──sessions/#历史会话记录两个关键文件auth.json保存APIKey，CCSwitch会自动维护它。config.toml指定模型、自定义provider、审批与沙箱策略。Windows路径：%USERPROFILE%\.codexmacOS/Linux路径：~/.codex记住：桌面版与CLI共用这个目录，所以用CCSwitch改一次，两边都生效。02·CCSwitchCCSwitch：用图形界面给Codex换不同的模型供应商它不是模型，而是一个配置管理工具：在图形界面里选供应商、填Key，它帮你写好auth.json与config.toml，随时在OpenAI、DeepSeek、智谱之间切换。①下载安装从项目Releases下载Windows版.msi（新手）或便携版zip，双击安装。②填供应商进入Codex配置区，填供应商名称、APIKey、BaseURL。③获取模型点"获取模型列表"，从下拉里选要用的模型名称。④重启改完Provider后重启Codex桌面版。来源：CCSwitch开源项目Releases页；普通用户选.msi安装包即可。02·国产模型接入常见OpenAI兼容服务的BaseURL参考服务商BaseURL备注DeepSeekCCSwitch有内置预设智谱GLM/api/paas/v4编程套餐另有coding端点硅基流动CCSwitch选SiliconFlow预设聚合DeepSeek/Qwen/GLM阿里百炼…/compatible-mode/v1需配workspaceIdOpenAI官方/v1默认，无需手填注意：有些供应商要带/v1，有些不带；若不支持ResponsesAPI，需在CCSwitch打开"本地路由映射"。来源：各厂商开放平台文档（DeepSeek/智谱/硅基流动/阿里云百炼）。02·手动配置不想用图形工具？直接编辑config.toml#~/.codex/config.tomlmodel="deepseek-chat"model_reasoning_effort="high"[model_providers.deepseek]name="DeepSeek"base_url=""env_key="DEEPSEEK_API_KEY"wire_api="responses"三个关键字段base_url服务商地址，注意/v1后缀env_key读哪个环境变量拿Keywire_apiresponses或chat，取决于供应商改完保存，重开终端执行codex验证。新手优先用CCSwitch，手动改config.toml适合需要精细控制的用户。02·报错排查接国产模型连不上？按这四个错误码对号入座401UnauthorizedAPIKey填错、没复制全，或没启用；检查Key前缀与服务商后台状态。404ModelNotFound模型名拼写与服务商不一致；在CCSwitch里重新"获取模型列表"再选。连接超时/拒绝BaseURL多了或少了/v1，或网络/代理问题；用curl先测一次地址。接口格式不兼容对方只支持ChatCompletions；在CCSwitch打开"需要本地路由映射"。排查顺序：先确认Key有效→再核对BaseURL→再选对模型名→最后确认wire_api格式；改完一律重启Codex。02·配置与接入国产模型CHAPTERTHREE核心使用与权限实践Chat与Project怎么选、三档权限分别什么时候用沙箱如何工作、模型与推理档怎么调、插件和技能装什么0303·工作模式推荐用Project模式，而不是每次开新对话Chat聊天临时问问题、写个小脚本；不绑定具体项目文件，适合一次性任务。Project项目（推荐）新建空白项目或直接选中已有项目文件夹；Codex能读到整个代码库，跨文件改、跑测试、连续迭代。Chat对话与Project项目两种入口03·核心使用与权限03·权限对话框左下角三档权限，决定Codex能多大胆地动手请求批准最保守·适合日常·每个写操作、每条命令都要你点确认·最安全，但频繁打断·适合第一次用、处理重要项目帮我批准日常推荐·沙箱内自动跑，不打扰·越界（写系统目录、联网）才提示·效率与安全的平衡完全访问风险升高·放开所有限制，可直接操控电脑·不审批、不隔离·仅在沙箱/容器内、可回滚时用默认从"请求批准"开始，熟练后切到"帮我批准"；"完全访问"不要在主力机上随便开。03·工作流一个任务的标准五步：从提需求到合并改动①选中项目指向已有代码库，或新建空白项目②描述任务用自然语言说要改什么、为什么③审查diff逐文件看它改了什么，不满意就叫停④跑测试它自己执行测试，失败会自己修⑤合并确认后合入，或让它开PR关键纪律：永远先看diff再批准——把"帮我批准"理解成它在沙箱里预演，不是它有权力直接动生产代码。03·核心使用与权限03·沙箱沙箱把Codex的操作关在一个盒子里，你决定盒子开多大沙箱模式能做什么什么时候用read-only只读文件、可运行、不可写让它先读懂项目、回答问题，不改动代码workspace-write可写项目目录内，禁动系统目录日常开发默认档；越界动作会弹出审批danger-full-access完全访问文件系统与网络仅在隔离容器/虚拟机里，配合版本回滚权限档位与沙箱模式是两件事：前者决定"要不要问你"，后者决定"它被允许做什么"。两者叠加。03·核心使用与权限03·沙箱原理为什么它删错文件也不会带走你的系统1·系统调用级隔离Codex跑的命令被限制在一个进程沙箱里，不能直接改写宿主系统目录。2·写操作白名单默认只允许写当前项目目录；想写到别处，必须停下来征求你的同意。3·网络默认收敛外发请求同样受沙箱策略约束，敏感操作不静默发生。沙箱围墙把智能体与宿主系统隔开03·核心使用与权限03·模型选择推理档low/medium/high：快与准的旋钮low反应快、便宜。改文案、写小函数、简单问答。medium默认档。日常功能开发、重构、写测试，平衡速度与质量。high深度推理。疑难bug、架构设计、跨文件重构，慢但更准。接第三方模型时，模型名在CCSwitch里选；推理档对应config.toml里的model_reasoning_effort。简单任务别开high，会白等几分钟。03·核心使用与权限03·扩展从"通用助手"到"你团队的助手"：插件与Skills内置工具，开箱即用读写文件、执行Shell、搜索代码、跑测试、浏览网页。不需要额外配置，模型自己决定何时调用。自定义Skills，沉淀团队规范在~/.codex/skills/放说明文件，让它按你的代码风格、测试命令、提交规范来干活。一个Skills文件长什么样#my-team/SKILL.md——写清项目结构、怎么跑测试、提交信息格式、哪些目录不能动Codex在相关任务时会自动加载这份说明。03·核心使用与权限03·命令速查CLI入门：记住这几条就够用codex#进入交互对话codex"帮我修这个bug"#带任务直接启动codex--help#查看全部参数codex--version#查看版本codexlogin#重新登录codexlogout#退出登录/model#对话内切模型/config#对话内看配置小技巧·在项目根目录启动，它才能读到完整代码库·交互里用/唤起命令列表·长任务用Ctrl+C优雅中止·不满意直接说"重来"，不要怕推翻03·核心使用与权限CHAPTERFOUR对比、风险与上手路线Codex与ClaudeCode怎么选、哪些红线不能碰常见问题、三阶段上手路线与下一步0404·对比不是非此即彼：两个工具擅长的事不一样Codex更擅长沙箱安全设计、Windows原生体验、开源CLI、批量后台任务、o系列深度推理。ClaudeCode更擅长大型代码库整体理解、长上下文、前端重构、架构级讨论；社区生态成熟。两类编程智能体的典型分工04·对比、风险与路线04·选型建议五条经验法则：把对的工具交给对的任务1Windows主力机、想接DeepSeek/GLM→优先Codex2大型代码库整体重构、前端UI重做→优先ClaudeCode3CI里批量跑任务、夜间无人值守修bug→CodexCLI更省心4对安全与审批敏感、不能让AI乱碰系统→Codex沙箱模型更安心5团队里两个都装：按任务切换，不要押注单一工具04·对比、风险与路线04·安全红线再顺手也别越过这五条线不要在主力机直接开"完全访问"需要时另开虚拟机或容器，改坏了能一键回滚。不要把含密钥的目录暴露给它

.env、SSH私钥、云凭证放进.gitignore，或用环境变量隔离。永远不要跳过看diff它一次改十几个文件时，逐行扫一遍至少能拦住明显错误。不自动装陌生依赖

pipinstall/npmi前先看一眼包名与版本。敏感数据不要贴进对话框客户数据、真实密码、生产地址先用脱敏示例代替。04·对比、风险与路线04·FAQ新手最常问的五个问题Q：它会取代程序员吗？短期不会。它替代的是重复性编码，需求拆解、架构判断、代码审查仍由人负责。Q：需要会写代码才能用吗？不要求，但能看懂diff、能跑测试，效率会高很多。完全零基础建议先学基础语法。Q：我的代码会被上传给模型厂商训练吗？商业版默认不用客户代码训练；接第三方模型时需另看该厂商的数据政策。Q：离线能用吗？不能。它是云模型，必须联网；本地只能用其CLI的离线缓存命令记录。04·对比、风险与路线04·上手路线给自己三周：从装完到真正用起来第1周·能用·装好桌面版并登录·用Chat问10个真实问题·改一个无关紧要的小脚本·全程开"请求批准"第2–4周·用好·用Project模式接真实项目·切到"帮我批准"·按需接DeepSeek/GLM·复杂任务用high推理档长期·沉淀·写团队专属Skills·把常用任务做成模板·评估是否接CI·定期复盘