2026年聊 AI Agent，Codex 是绕不开的一个名字。作为 OpenAI 出品的全能型 AI Agent，它把写代码、改文件、跑命令、生成图片这些能力整合进了同一个交互会话里，默认底层跑在 GPT-5.5 上，视觉理解与图像生成则交给 Image-2 模型负责。很多人以为它是程序员专属，其实只要你描述得清楚自己想让电脑干什么，零基础一样能把它用起来。
我翻了翻社区和搜索框里的高频问题，发现大家卡住的点出奇一致：不是不会用，而是不知道 Agent 和普通聊天机器人到底差在哪，然后倒在了安装、登录、模型接入这些"第一公里"上。这篇就把从概念到实战、从装好到跑通的完整链路拆开讲一遍，顺便把你大概率会遇到的几个报错也一并解决掉。
1. 别急着敲命令：先分清 Agent、LLM 和基础模型
1.1 DeepSeek 到底是哪种"AI"
很多人刚接触时会问："DeepSeek、GPT 这些不都是 AI 吗，和 Agent 有什么区别？" 我用一句话回答：DeepSeek、GPT-5.5 这类模型，本质是LLM（大语言模型），它们是"大脑"；而Agent是"大脑 + 手脚 + 工具"的完整系统。
打个比方。LLM 就像一个刚入职的高材生，知识量很大，你问他什么他都能答上来，但他不会自己打开电脑、不会查数据库、不会发邮件。Agent 则是一个带工具的老师傅：他同样懂很多知识，但他会看任务、定计划、打开终端执行命令、读文件、调用外部接口，做完一步还会回头看结果对不对，错了就换个方式再试。Codex 就是这样一个"老师傅"，而且它特别擅长干活，不只是聊天。
1.2 Agent 的组成结构
根据社区里经常讨论的"Agent 组成结构"这个话题，一个完整的 Agent 通常包含四层：
- 大模型内核：负责理解和推理，相当于决策中枢。Codex 默认是 GPT-5.5，处理动态任务时还可以切换到其他模型。
- 工具集：让 Agent 能执行实际动作，比如 Shell 命令、文件读写、图片生成、浏览器操作。Codex 的工具主要是终端和文件系统，配合 Image-2 后还能看图、生成图。
- 记忆系统：短期记忆是这个会话里说过的话，长期记忆则是项目偏好、历史经验。Codex 通过
AGENTS.md文件和 Memory 功能来保存长期信息。 - 编排循环：也就是"思考-行动-观察-再思考"的闭环。Agent 干完一步会自动检查输出，决定是继续还是停止。
你如果搜过"AI agent harness 自动化运维"，会发现 Codex 其实就是一个非常典型的 harness，翻译过来就是"套在模型外面、驱动模型干活的外壳"。模型本身不执行命令，是 Codex 这个 harness 在执行，并把执行结果喂回给模型，形成一个完整的自动化闭环。
1.3 搞清楚这些概念再上手，到底有什么好处
好处很直接：你不会再对它产生错误期待。
很多人把 Codex 当成聊天机器人，问一句"给我写个贪吃蛇"就等着收成品。实际上 Codex 更适合的用法是，你告诉它"在当前目录新建一个前端项目，写完启动起来，浏览器能打开，并且帮我截图检查页面是否正常"。它会把任务拆成很多步：初始化项目、装依赖、改代码、起服务、截图、看截图、修问题。整个过程里你要做的只是描述目标，偶尔在关键节点给一句确认。
理清这层关系，后面所有的配置和实操都会顺很多。因为不管是安装、登录还是报错排查，你都得先知道：Codex 是个执行引擎，有一堆配置文件和外部依赖，而不仅仅是"一个网页对话框"。
2. 从安装到登录：本地环境的完整落地方案
2.1 环境准备：Windows、macOS 与 Linux 该怎么办
Codex 目前主流的安装方式有两种：命令行工具和桌面客户端。命令行版支持 macOS 和 Linux，Windows 上可以通过 WSL 跑，也可以在 Windows 原生环境里跑桌面版或通过 Node 直接安装。我个人的建议是：
- 如果你只是尝鲜、想快速体验，直接装桌面版。
- 如果你后续要做自动化、接 MCP、写 Skill，优先用命令行版，因为配置文件和终端操作都在命令行里更直接。
无论哪种方式，电脑上最好先有 Node.js 18 以上版本和 Git，因为 Codex 很多能力依赖这两个基础工具。用命令行装很简单：
npm install -g @openai/codex装完以后执行：
codex --version能输出版本号就说明安装成功。如果你在 Windows 上装桌面版，双击安装包一直到完成即可；如果遇到"Windows 安装未完成"的提示，一般是权限不足、杀毒软件拦截、或安装包下载不完整，右键以管理员身份运行安装包，或者重新下载一次基本都能解决。
2.2 登录与授权：别在第一步就卡住
安装好以后，需要登录 OpenAI 账号才能用。命令行下执行：
codex login会跳转浏览器完成授权。如果把"登录入口"这一页弄丢了，也可以直接访问官网的 Codex 页面，登录后回到终端刷新状态。
这里有个高频报错：auth token is unavailable。我碰到过两次，第一次是刚装完没有执行 login，第二次是登录态过期。解决思路是：先手动执行codex login重新授权；如果已经登过但还是报错，多半是本地保存登录信息的文件损坏或权限不对，把它删掉重新登一次即可。不同系统路径略有差异，一般在用户主目录下的.codex配置目录里，找到 auth 相关文件删除掉，重新执行codex login，问题就消失了。
提示：不要直接复制网上别人贴的 token 到配置文件里。Codex 的会话令牌和开发者 API Key 是两套机制，手动指定反而容易让
auth token is unavailable变得更顽固。
2.3 启动一次：让 Codex 生成默认模型目录
安装完成后，很多人会直接codex进入对话，然后立刻碰到model catalog template 'gpt-5.5' not found这类报错，一脸懵。
这个问题的本质是：Codex 第一次运行时，会根据当前版本生成一份"模型目录"配置文件，记录它能调用的模型清单、API 端点和服务参数。如果你的版本比较老、或者配置文件被第三方工具改坏，它找不到gpt-5.5这个模型的模板，就会直接罢工。
处理办法很简单：先手动完整启动一次 Codex，让它把默认的模型目录生成好。如果已经报错了，就先退出，找到 Codex 的配置目录，把配置文件备份后删掉，再次执行codex，让它重新初始化。初始化完成后，再在模型选择界面里确认能看到 GPT-5.5 和 Image-2 的条目。
这一步非常关键，因为后面接入第三方模型、设置本地服务，全部都要在这个模型目录的基础上改。地基没打好，后面的配置全是空中楼阁。
3. 模型接入实战：GPT-5.5、Image-2 与 DeepSeek 的配置思路
3.1 Codex 是怎么找到 GPT-5.5 和 Image-2 的
Codex 内部维护了一份"模型目录"（model catalog），里面记录了每个模型 ID 对应的调用地址、上下文长度、是否支持视觉、是否支持工具调用等元信息。GPT-5.5 是默认的推理模型，负责对话和决策；Image-2 是多模态模型，负责看图、生成图片和视觉理解。
你不需要背这些参数，但需要知道：当你在 Codex 里切换到某个模型时，它其实是去模型目录里查配置，然后向对应的端点发请求。所以如果目录里某个模型不存在，或者版本不对，就会报not found或not supported。
3.2 官方模型的常见配置
如果你只是想用官方能力，通常什么都不用配。在 Codex 对话界面输入/model可以切换模型，选中gpt-5.5作为推理模型即可。需要图片生成时，Codex 会自动调用 Image-2，比如你让它"画一张项目架构图"，它就会调 Image-2 生成图片文件，然后告诉你图片保存路径。
这里有个值得注意的点：Image-2 不只是"画图工具"，它还是一个很强的视觉理解模型。Codex 在查看截图、分析页面布局、检查前端样式时，依赖的就是它。换句话说，Image-2 是 Codex 这双"眼睛"，而 GPT-5.5 是它的"大脑"。两者分工明确，配合起来才能完成真正的多模态 Agent 任务。
3.3 把 Codex 接到 DeepSeek：配置文件怎么改
社区里问"Codex 接入 DeepSeek"的人非常多，原因也简单：DeepSeek 是国产开源大模型，性价比高，很多人希望用它当 Agent 的推理内核。实现思路并不复杂，因为 DeepSeek 提供的是 OpenAI 兼容接口，Codex 只要把 API 基址指过去就行。
我一般在配置文件（如~/.codex/config.toml）里用一个自定义 provider，把模型 ID 和端点指过去，大致结构如下：
[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "openai"然后在模型目录里加一个条目，把gpt-5.5-sol这类内部模型 ID 对应到 DeepSeek 的模型名上。不同版本的 Codex 对模型目录的处理方式不太一样，所以最稳妥的做法是：先在模型目录里找到官方模型的模板，复制一份，改名为你想用的 ID，再把 provider 指到 DeepSeek。
注意：不同版本的配置字段名可能有差异，改完以后先用
codex --version确认版本号，再看官方文档对应版本的说明。别把网上搜到的旧配置直接套用，否则很容易出现model not supported之类的报错。
3.4 遇到gpt-5.6-sol is not supported怎么办
搜索结果里还有一条高频报错，意思是某个模型版本不被当前 Codex 支持。出现这个报错，通常有三个原因：
- 模型名拼写或大小写不对。Codex 对模型 ID 的匹配是严格区分大小写的。
- 模型目录里没有该模型的条目。你手动在环境变量里写了模型名，但目录里没注册，就会报 not supported。
- 当前 Codex 版本太老。新版模型上线后，旧版客户端的模型目录里根本没这个 ID，自然用不了。
解决路径也清楚：升级 Codex 到最新版，然后在模型目录里检查该模型是否存在；如果是自己拼的名字，改成官方目录里的标准 ID。
4. 第一个多模态 Agent 任务：从需求拆分到 Skill/Memory/MCP 落地
4.1 一个能跑通的完整示例：让 Codex 帮你做一份带配图的项目周报
说了这么多概念和配置，下面用一个真实任务走一遍流程。假设你手头有一个社区团购的小程序项目，需要整理本周开发进展并生成一张宣传配图。传统做法是你自己写周报、找设计师作图，现在把这整件事交给 Codex。
你可以这样向它描述任务：
请先查看当前项目的 README 文件和最近提交记录（git log -5）， 总结出本周主要完成的 3 个功能点， 然后基于这些内容生成一份英文版项目周报， 最后使用 Image-2 模型生成一张适合发布在团队群里的横版宣传图， 图片风格偏科技感，配文要包含周报里的核心功能关键词。这个描述里包含了三个关键要素：背景（项目文件在哪）、目标（生成中英文周报和宣传图）、质量标准（3 个功能点、科技感、横版）。Codex 会自己拆解成步骤：先读文件、再看日志、然后写周报、最后调 Image-2 生成图片。
4.2 为什么要把任务"拆得清楚"，而不是只说一句话
很多初用者失败，是因为把 Codex 当成许愿池，喊一句"帮我写周报"就觉得够了。实际使用中，任务描述越清晰，Agent 的执行成功率越高。原因是模型有上下文窗口，也有推理深度，你越早把约束条件给它，它越不需要瞎猜。
这里有一个实用的描述模板，我一直在用：
角色：你是一名资深的 XX 岗位同事 背景：我在做 XX 项目，相关文件在 XX 路径 任务：做 XX，拆成几步完成 约束：用 XX 风格 / 不处理 XX / 输出到 XX 文件 验收：完成后告诉我结果，并且列出你改过哪些文件按照这个模板写需求，Codex 的完成质量会明显高一截。
4.3 Codex 是如何"查看文件"的
搜索里有不少人在问"AI Agent 如何查看文件"。对 Codex 来说，它有两个手段：
- 直接读取文本类文件：代码、Markdown、JSON、日志，它都能直接读。
- 执行终端命令：比如
ls、cat、git log，它会自己决定该看哪个文件。
你不需要手动告诉它"文件在哪"，只需要在任务描述里给出相对路径或者项目根目录，它自己会去翻。如果它反复读不到某个文件，多半是权限或者路径问题，你可以在对话里直接问"你当前的工作目录是什么"，让它先pwd一下再继续。
4.4 Skill 与 Memory：把常用能力固化下来
如果你希望 Codex 不只是"用一次拉倒"，而是越用越顺手，一定要用好 Skill 和 Memory。
Skill 相当于给 Agent 预置的"行为说明书"。你可以在配置目录的 skills 文件夹里新建一个weekly-report/SKILL.md，内容大致是：
--- name: weekly-report description: 生成项目周报的固定流程 --- 1. 读取项目 README 2. 使用 git log 获取最近 10 条提交 3. 归纳为 3-5 个功能点 4. 按照固定模板输出中英文周报配好以后，下次只要说"用 weekly-report 技能写周报"，它就会严格按照这个流程走，不需要你重复说明。Memory 则更像长期记忆，Codex 会读取项目目录里的AGENTS.md文件来了解你的项目偏好，比如"这个项目用的是 React + TypeScript，测试必须跑npm run test"。把这些约定写进AGENTS.md，Agent 就会一直遵守。
4.5 MCP：让 Agent 长出更多"手"
MCP（Model Context Protocol）这几年讨论度很高，简单理解就是给 Agent 提供一个标准插槽，让它可以接入更专业的外部工具。比如你可以在 Codex 里接：
- n8n 工作流，让 Agent 触发自动化任务；
- 日历服务，让 Agent 帮你安排会议；
- 数据库客户端，让 Agent 直接查询数据；
- 浏览器扩展，让 Agent 操作网页。
命令行下一般用类似下面的方式添加 MCP 服务：
codex mcp add your-service-name -- npx your-mcp-server添加成功后，Codex 在任务中需要时就会自动调用这些工具。比如你让它"检查一下明天的会议安排，并整理成待办事项发到群里"，它就会通过 MCP 调起日历服务，然后调起消息服务发出结果。这一整条链路，就是大家常说的"AI Agent 多模态功能"在真实场景中的落法。
5. 日常工作流里的几个翻车现场与对应解法
5.1model catalog template 'gpt-5.5' not found到底该怎么治
这个报错我在第四节已经提过根因，这里再给出完整的排查链路，因为它出现的概率实在太高。
现象：执行codex进入对话，输入内容后立刻报找不到模型模板。
排查步骤：
- 先确认 Codex 版本，
codex --version，如果版本低于当前最新版本，优先升级。 - 找到配置目录，看是否存在模型目录文件。没有的话，删掉整个配置目录备份，然后重新执行
codex，让程序自己初始化。 - 如果文件存在但内容为空或只有很少的条目，说明模板生成失败，通常是网络请求被中断或权限不够写文件。
- 解决后，用
/model命令检查模型列表里是否有gpt-5.5。
值得注意的是，网上有些教程会让你手动"注册"一个叫gpt-5.5的模板，这种情况下问题更容易反复。因为模板内容不完整，后续调用照样失败。正确做法永远是先让官方程序自己生成完整的模型目录，再在它基础上做修改。
5.2auth token is unavailable的三种情况
这个报错我在登录节提过，但实际工作中我发现它有三种变体：
| 报错场景 | 根因 | 处理方式 |
|---|---|---|
| 刚安装完直接使用 | 还没登录 | 执行codex login |
| 之前能用，过了一天突然不行 | 登录态过期 | 重新执行codex login |
| 手动改过配置文件或环境变量 | token 指向错了 | 删除本地 auth 文件后重新登录 |
第三种情况最隐蔽。有些教程会让你把 API Key 写成环境变量，结果把 Codex 自带的登录态覆盖掉了。如果你不想用 API Key 方式，就把环境变量删掉，回到官方登录方式；如果你想用 API Key，就得保证配置里的身份认证部分完全一致，不要两种混着来。
5.3cc switch local proxy failed while handling codex endpoint /responses的排查思路
这条报错在搜索框里出现频率也很高，很多人的第一反应是"我的网络出问题了"，实际没这么玄乎。这个错误通常只有一个含义：Codex 把请求发到了一个本地服务，但这个本地服务没有正常工作。
什么情况下 Codex 会把请求发到本地服务？最常见的是你配置了自定义 API 网关。比如为了接入多个第三方模型，或者让请求统一走某个本地聚合服务，你在配置文件里把 base_url 指到了类似http://localhost:xxxx的地址。Codex 每次调用/responses接口，都会先经过这个本地网关，网关没启动、端口写错、服务崩溃，就会报上面的错。
排查顺序如下：
- 看配置文件里的 base_url 指向哪里，确认是本地地址还是官方地址。
- 用
curl测试该地址是否真的在监听，比如curl http://localhost:xxxx/v1/models。 - 如果服务没起来，启动它再审一次。
- 如果服务起来了但依然报错，多半是路径不匹配，Codex 请求的是
/responses，你的网关没有把这个路径转发到上游。 - 实在排查不出来，就先把 base_url 切回官方默认地址，确认 Codex 本身没问题，再回头排查网关。
我见过有人把这个报错归结为"地区网络问题"，然后费很大劲去弄各种复杂的网络工具，最后发现只是本地网关少启动了一个进程。这里想提醒一句：遇到这个报错，先把精力放在"本地服务是否正常"这个方向上，不要往其他地方想。
5.4gpt-5.6-sol不被支持，和模型目录的关系
这条报错其实是 5.1 的镜像问题。gpt-5.6-sol这个 ID 大概率是你从别人配置里复制过来的，而当前模型目录里根本没有这个条目。Codex 在处理模型 ID 时会先查目录，查不到直接拒绝。
处理方式：在模型目录里搜索看有没有这个 ID，没有就换成自己目录里真实存在的 ID，或者按照官方文档补全这个模型的注册信息。这里想额外提醒，不要盲目追求"新版本模型 ID"。稳定可用的模型比名字听起来很新的模型更重要，尤其在自动化流程里，一个能稳定调用 100 次的模型，远好过一个三天两头 not found 的模型。
5.5 Windows 下 Codex 打不开、安装不完整的补救方法
最后集中说下 Windows 上的问题。codex 打不开、codex windows 安装未完成、codex 打不开这几个问题往往是一套原因：
- 安装包下载不完整：重新下载，校验文件大小；
- 权限不足：右键管理员运行；
- Node.js 版本过低：命令行版在旧 Node 环境下会静默失败，升级到 Node 20+ 再试；
- 终端策略限制：Windows 上 PowerShell 执行策略可能拦截脚本，用管理员权限执行
Set-ExecutionPolicy RemoteSigned后重试。
如果是桌面版双击没反应，可以先试试命令行版，至少能通过终端输出定位问题。记住一个原则：先看报错信息，再去问人。Codex 的坑基本都是配置问题，不是玄学问题，报错信息里通常已经把原因写得明明白白。
最后分享一点个人体会。Codex 这类全能型 Agent 真正改变的不是"写代码"这个环节，而是整个工作流的组织方式。以前我做个数据分析报告，要自己写脚本、跑数据、做图、排版；现在我把目标说清楚，它自己拆步骤、执行、检查、迭代，我只需要在关键节点把把关。但它也不是万能的，任务描述含糊、项目文件混乱、期望一步到位，照样会翻车。
如果你刚上手，我的建议特别简单：先从 5.1 和 5.2 这两个坑开始，确保安装和登录不再出问题；然后跑通 4.1 那个周报任务，感受一下完整流程；最后再逐步加入 Skill、Memory、MCP，把它从"好用的助手"变成"懂你的同事"。整个路线走完，你就不需要再看任何教程了。
