我把这套"Codex AI 编程实战课：Codex 智能体实战，从零系统学习智能体应用"从头到尾完整过了一遍。标题里的两个关键词——Codex 和智能体，恰好是今年做 AI 应用绕不开的两个方向：Codex 是 OpenAI 推出的 AI 编程工具，本质是一个能理解需求、动手改代码、主动执行命令的编程智能体；智能体（Agent）则是那种"有目标、有计划、能调用工具、自己迭代完成工作"的 AI 应用形态，而不是只会在对话框里回话的聊天机器人。这门实战课带我从命令行开始，把一个能真正干活的智能体应用从零搭了起来，整个过程走完，我对"智能体应用"这件事的理解发生了质的变化。
说结论：如果你已经会一点 Python，也接触过 ChatGPT 这类对话式 AI，但一直没搞明白"智能体"到底和普通问答有什么不一样，这门课值得完整跟一遍。它不要求你先会大模型原理，也不逼你啃论文，全程就是"装环境、跑命令、看效果、改代码"。我带过不少刚入门的朋友，大家最容易卡住的地方其实不是概念，而是不知道代码放哪、环境怎么配、Agent 的执行循环怎么跑起来。这门课最有价值的地方，就是把这些"最后一公里"的问题一次性讲透。
我跟着实战课走了一个完整的项目：做一个文档整理智能体。给它一个乱糟糟的文件夹，里面有图片、PDF、Markdown、CSV 和 Python 脚本，文件名和内容还经常对不上，它需要自己读文件、判断类别、移动归档，最后生成一份整理报告。听起来简单，但里面正好包含了智能体应用最核心的几件事：任务拆解、工具调用、循环执行、失败重试。把这几件事搞明白，后面你想做销售智能体、考公智能体、企业内部知识库助手，思路完全一致。下面我把完整步骤、参数配置和踩过的坑都写出来，照着做就能复现。
1. 这套实战课到底在教什么
1.1 Codex 和智能体到底是什么关系
很多人第一次看到 Codex，第一反应是"这不就是个能写代码的 ChatGPT 吗？"这个印象对了一半。ChatGPT 的问答模式，本质是"人拿到文字，再手动复制、保存、运行、看报错、贴回来"的人机循环，代码生成得再好，动手干活的还是人。Codex 不一样，它拿到需求后会自己拆解：看项目结构、决定改哪个文件、执行哪条命令、跑测试、读报错日志、修代码、再跑一次。整个流程是典型的 Agent 循环——感知、决策、行动、观察、再感知。这才是它被称为"智能体"的根本原因。
这门课的第一个模块，就是把这个循环拆给学员看。做智能体不是写一大段提示词让模型去"生成"，而是要设计一套机制，让模型在每一步都能看到当前状态、决定下一步动作、调起对应工具、拿到结果并继续迭代。理解了这个循环，后面学什么 Dify、Coze、LlamaIndex 都会轻松得多，因为所有框架的本质都是在帮你实现这个循环。
1.2 这套实战课适合谁来学
我主观判断一下，以下三类人跟完这堂课收益最大：
- 会被重复性文件处理、代码修补、批量整理工作烦到的开发者。这类人平时写脚本不算难，但每次换一个需求都要重写一套逻辑，用 Codex 之后会发现"描述需求给智能体"比"自己写脚本"省力得多。
- 想做 AI Agent 开发，但不知道从哪下手的新人。课程用的是"先跑起来、再讲原理"的节奏，推进很平滑。
- 已经在用 Dify 或 Coze 搭过智能体，但觉得平台封装太重、想理解底层逻辑的人。代码优先的路线能补上这块短板。
如果完全没写过代码，上来直接跟还是有点吃力。建议先补一点 Python 基础，只需要会读文件和调用函数就够。课程里涉及业务代码的部分，大多是以模块形式给的，你不需要从零写算法，重点是理解"智能体怎么调用这些工具完成任务"。
2. 为什么用 Codex 学习智能体：选型逻辑拆解
2.1 智能体和普通 AI 问答的本质区别
这套课程反复在强调一个观点：没有工具的 AI 只能提建议，有了工具的 AI 才能完成工作。普通问答模型是一个封闭的"文本进、文本出"系统，你说一句它回一句，它不会主动去查数据库、不会帮你打开文件、不会执行环境里的命令。而智能体应用的标志性特征，就是它可以挂载工具——文件读写、终端命令、HTTP 请求、代码搜索、数据库查询，等等。模型负责"思考"和"决策"，工具负责"动手"和"感知"。
举个最简单的例子：你问普通 AI"帮我统计这个目录下有多少个 Python 文件"，它只能给你一个大概的回复范本，因为你没有把目录内容给它。但 Codex 这类智能体会自己去"看一眼"目录，调用 shell 工具执行ls -R，数完文件再告诉你结果。这个差别就是"聊天机器人"和"智能体"的分水岭。
课程中花了很大篇幅讲解如何为智能体设计工具调用的边界。比如，给文件整理智能体提供"读取文件内容"这个工具，但明确禁止"修改文件内容"，这就是在设计权限边界。没有边界，智能体在执行复杂任务时可能做出危险操作；边界太死，它又什么都干不了。如何平衡，是每个做 Agent 应用的人都必须面对的课题。
2.2 Codex 与 Dify、Coze 这些平台的路线对比
现在智能体开发工具非常多，Dify、Coze（扣子）、FastGPT 都是很火的低代码平台，主打可视化编排。课程里没有一上来就推平台，而是先让学员用 Codex 走一遍"代码优先"的路线，这个选择很有讲究。
两条路线的差异，我用一张表格说清楚：
| 对比项 | 可视化平台（Dify/Coze） | 代码优先（Codex CLI） |
|---|---|---|
| 上手门槛 | 低，拖拽节点即可 | 中，需要熟悉命令行和代码结构 |
| 逻辑复杂度承载能力 | 中等，节点一多就混乱 | 高，所有逻辑都在代码里 |
| 自定义工具接入 | 部分平台支持，但有格式限制 | 灵活，Python 模块直接挂载 |
| 版本管理和复用 | 较难，配置存在平台上 | 容易，纯代码可走 Git |
| 适合场景 | 快速验证、运营搭建 | 深度定制、工程化落地、学习原理 |
我的建议是：如果你只是想给公司快速做一个知识库问答助手，Dify 一周内就能上线，这没问题。但如果你想系统学习智能体原理，或者后面要做带复杂逻辑的业务系统，代码优先路线会更扎实。课程选 Codex 打底，目的就是让你先摆脱可视化平台的"拐杖"，真正理解 Agent 的工作机制。
2.3 Codex 的优势、劣势和使用边界
Codex 做智能体实战有三大优势：
第一，它对代码类任务的执行力稳定。默认模型在处理补丁生成、报错修复上表现很好。我实测过一个场景：让它改一个 Python 库的内部函数，它能准确找到调用链并修改，比很多开源模型靠谱。
第二，自带 CLI，天然适合工程化。终端里就能和它结对编程，它可以直接读本地项目、运行测试、处理 Git 提交，这是桌面版和网页版替代不了的。
第三，支持自定义工具扩展。你可以把自己的 Python 模块挂进去，等于给智能体装上了"任意门"。课程里做的文件整理智能体，就是通过这种扩展实现的。
劣势也很明显：
- 默认模型服务是 OpenAI 的，国内用户通常需要把 provider 切换到 DeepSeek 等可以正常访问的合规模型服务商，这块配置对新人有点门槛。
- CLI 的配置概念不少：auth token、base_url、wire_api、model_provider，文档和一些网上的教程写得比较零散，第一次接触容易懵。
- 它不是万能的。遇到特别复杂的需求，它仍然需要你先做好方案拆分，该画架构图、该设计数据模型的时候，不能省。
提示：下面是安装和配置的全过程，我默认你使用官方渠道下载的版本，并且通过合规的账号注册和模型服务接入方式操作。命令和错误信息来自我的实际运行记录，不同版本可能略有差异。
3. 环境与配置：从安装到接入模型的全过程
3.1 三种安装方式怎么选
课程介绍了三种装 Codex 的方式：桌面版、CLI 版、网页版。桌面版有图形界面，安装包下载后一路点下一步就行，适合不爱碰命令行的朋友；网页版最轻量，适合临时体验；CLI 版是在终端里操作的，适合做工程化开发。我最终选的是 CLI 版，原因很简单：只有 CLI 版能直接读取当前目录的上下文、调用本地工具、执行 shell 命令，而这些能力正是智能体应用最需要的"手脚"。桌面版虽然用户体验好，但在自动化脚本和批量处理场景里，灵活性差不少。
CLI 版安装命令也不复杂，二选一：
# npm 全局安装（需要先装好 Node.js 18+） npm install -g @openai/codex # 或者用 Homebrew brew install codex装完以后，在终端输codex --version能打印版本号就说明装好了。紧接着是登录流程，第一次启动时执行：
codex login它会弹出一个浏览器页面，完成账号授权后，本地会自动保存认证信息。这一步是新人最容易慌的地方，因为终端会滚动输出一堆日志，看起来像报错，其实只是认证状态提示。我当时的经验是：先确认终端最终输出的是登录成功的信息，再往下进行，否则后面所有请求都会报认证错误。
3.2 Windows 桌面版安装的几个细节
课程里 Windows 用户占比不低，桌面版安装我单独提两句。安装包一定去 Codex 官网或者 GitHub Releases 官方发布页面下载，不要从搜索引擎里随便点第三方下载站。这类工具软件是重灾区，很容易碰到高仿站点，下载到带后门的版本就得不偿失了。
Windows 版装好后有两个细节要注意。第一，首次启动需要登录，登录体系跟 CLI 版是同一套，认证信息可以共享，两个版本配合使用问题不大。第二，安装路径别带中文和空格，我见过有人装到C:\Program Files\Codex这种带空格的路径，后面模型缓存和项目路径拼接时偶尔会出问题。建议手动指定一个纯英文目录，实测下来最省心。
3.3 把默认模型切换到 DeepSeek 的配置方法
这是整个实战课里实操价值最高的一节。Codex 默认调用 OpenAI 的模型服务，但很多人会把它切换到 DeepSeek 这类可以正常注册和访问的国内模型服务商。切换的核心是修改配置文件，以 CLI 版为例，配置文件在~/.codex/config.toml。
打开配置文件，找到model_providers段落，加一个新的 provider 配置（下面是一个基础示例，字段以你的模型服务商和 Codex 版本说明为准）：
[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" api_key_env_var = "DEEPSEEK_API_KEY" wire_api = "responses"然后在配置文件的模型设置区域，把 provider 指向 deepseek，并指定模型名（比如deepseek-chat或deepseek-reasoner）。保存后重启 Codex，请求就会走 DeepSeek 的通道。
这里有几个坑我必须反复强调：
base_url一定要注意，域名后面的路径版本不能省略，也不能写错，否则请求直接 404。wire_api是有讲究的。Codex 对不同的接口规范有不同的解析方式，要看服务商到底兼容哪一种协议，两者对不上，就算 key 正确也调不通。- 切换完模型后，先跑一个最小任务验证链路，比如让 Codex 执行一句最简单的命令或生成一个 hello world 文件。千万别一上来就丢一个几万字的项目，那样一旦报错，你根本分不清是模型问题、配置问题还是网络问题。
3.4 核心配置项逐个说明
为了让你后面自己配置时不抓瞎，我把config.toml里最常用的字段整理成了对照表。这些参数我在跑完整个项目之后才算真正理解，新人阶段光看官方文档确实容易一头雾水。
| 配置项 | 作用 | 建议 |
|---|---|---|
model_providers.<名称>.base_url | 模型服务的接口地址 | 不同服务商不同，注意域名和版本路径 |
model_providers.<名称>.api_key_env_var | API Key 对应的环境变量名 | 不要硬编码 Key，用环境变量传递 |
model_providers.<名称>.wire_api | 接口协议类型 | 常见为 responses 或 chat completions，按服务商文档确定 |
model | 默认模型选择 | 写清楚 provider 和模型名 |
model_reasoning_effort | 推理强度 | 日常任务 medium 够用，复杂任务可调高 |
experimental_use_gpt_codex | 是否启用实验性代码执行能力 | 默认关闭，需要自动化执行再开启，注意安全边界 |
3.5 环境变量设置与安全边界
讲完配置字段，必须补一句环境变量的设置。API Key 通过环境变量传入，不要在配置文件里明文写死。我习惯在~/.zshrc（Windows 是系统环境变量面板）里加一行：
export DEEPSEEK_API_KEY="sk-你的key"改完记得重新加载配置或者新开终端窗口，不然环境变量不生效，codex启动时会一直报 key 缺失或认证失败。我在实战期间碰到过好几次，说穿了都是这个原因。
安全边界同样不能忽略。Codex 作为智能体，是有权限执行 shell 命令的，这意味着它可能改动你的文件、调用网络、安装依赖。我的建议是：实验阶段在独立的目录里跑，不要直接在重要项目的根目录下令它干活。课程项目的目录我都是单独建的，容器隔离或备份目录是基本功，等熟练之后再逐步放开权限。
4. 实操：从零搭一个文档整理智能体
4.1 项目目标和能力拆解
课程里的进阶项目，我挑了一个最有代表性的：文档整理智能体。需求是：一个文件夹里散落着图片、Markdown、PDF、CSV、Python 脚本，命名乱七八糟，有的文件内容跟文件名完全不搭。智能体要做的是：读取所有文件，按内容类别归档到images/、docs/、data/、code/子目录，最后生成一份report.md，逐条说明每个文件的去向和分类依据。
选这个项目是因为它代码量不大，却能覆盖智能体的五类核心能力：文件读取、工具调用、循环决策、异常处理、结果输出。做完它，你对"智能体能帮我干什么"会有非常具体的体感，而不是停留在概念层面。
4.2 环境准备和项目结构
开始之前，按这个清单检查环境：
- Codex CLI 已安装，
codex --version能正常输出版本号 - 已完成登录认证
- 已配置好模型 provider，比如接入 DeepSeek
- 已设置
DEEPSEEK_API_KEY环境变量 - 建好独立测试目录，比如
~/agent-lab/cleanup-demo
先跑一句最小任务验证：
codex exec "print current directory and list files"它能正确输出当前目录和文件列表，说明 Codex 已经能访问本地环境，Agent 的"手脚"已经接上了。这一步非常关键，后面所有操作都建立在"Codex 能感知环境"这个基础上。
然后创建项目结构：
cleanup-demo/ ├── AGENTS.md ├── tools/ │ ├── __init__.py │ ├── file_classifier.py │ └── mover.py ├── inbox/ # 待整理的文件 └── output/ # 整理结果AGENTS.md是给 Codex 看的说明文件，里面写清楚任务边界、可用工具、禁止操作。这个文件的地位相当于给智能体"立规矩"，课程里反复强调：Agent 项目里的提示词不是随手丢给模型的一句话，而是系统化的工作说明书。
file_classifier.py我写了一个基于文件后缀加内容关键字的简单分类函数，mover.py负责移动文件并记录日志。这两个小模块就是智能体要调用的工具，也可以理解成给 Agent 准备的"工具箱"。
4.3 让 Codex 自己写代码并迭代
项目结构就位后，进入最关键的环节：让 Codex 自己干活。在交互模式里输入下面这段需求：
请完成文档整理智能体的核心逻辑： 1. 读取 inbox 目录下所有文件； 2. 对每个文件调用 tools/file_classifier.py 中的 classify 函数判断类别； 3. 调用 tools/mover.py 中的 move_file 函数把文件移动到 output 下的对应子目录； 4. 最后生成 report.md，逐行记录文件名、原路径、目标路径、分类依据； 5. 不要修改任何文件内容，只做移动和记录。Codex 会读取AGENTS.md、查看项目结构、理解已有工具模块，然后开始写代码。期间它会自己运行测试命令，如果报错会读 traceback、改代码、再跑一次，直到满足要求。整个过程基本不用手动敲业务代码，你只需要观察它的动作，偶尔纠正方向。
我第一次看到它自己修好一个路径拼接的 bug 时，确实被震撼了一下。这个 bug 如果是我自己写脚本，至少要跑一遍才可能发现，而 Codex 在测试失败后主动读取了 traceback，定位到是 Windows 风格路径和 POSIX 风格路径混用导致的，然后自己改了逻辑并再次运行验证。这就是智能体应用和普通脚本的最大区别：前者能够自主感知失败、分析原因、修正策略。
4.4 结果验证和调试循环
跑完后，查看output目录。正常情况下，会出现images/、docs/、data/、code/几个子目录，每个文件都在正确的位置，report.md里的记录也能对上。
如果结果有偏差，比如某个 PDF 被放到了data目录，先别急着手动改文件。在对话里追加一句反馈，比如"report.md 里第 3 条分类依据似乎不对，请重新判断"，Codex 会重新审视文件内容并修正。这就是智能体应用的核心体验——支持自然语言反馈的调试循环。它不完美，但它可以持续对话、持续修正，直到达到你的要求。
提示：实验阶段，所有待整理的文件最好先复制一份到备份目录。虽然 Codex 移动文件出错概率不高，但万一目录权限或路径拼接出问题，原始文件被误删就很麻烦。这个习惯我一直保持，后面做任何 Agent 实验都沿用这套"备份为先"的做法。
5. 常见问题与排查实录
5.1 "cc switch local proxy failed while handling codex endpoint /responses" 怎么处理
这个报错我在配置过程中遇到过，追踪下来基本是本地接口转发环节出了问题。简单解释：Codex 发起请求时，会经由一个本地的接口转发配置，如果这个环节没对上，日志里就会出现类似codex endpoint /responses处理失败的信息。常见诱因有三个：
- 本地配置指向的服务没有启动，或者地址端口写错了；
- 配置文件里的
base_url和转发规则冲突； - 系统层面的网络策略限制了本地回环地址的访问。
排查顺序建议这样走：先确认你配置的模型服务地址本身能访问，用 curl 直接打一下接口看看返回；再检查是否有其他网络工具占用或拦截了本地接口；最后回头核对config.toml里的base_url和wire_api是否一致。大部分情况下，把配置恢复成清晰、简单的直连模式就能解决。
5.2 "codex auth token is unavailable" 是什么原因
这个报错几乎可以断定是认证状态出了问题。如果是第一次安装就遇到，执行一遍codex login重新认证即可。但如果是登录成功后隔几天再打开遇到，重点检查两个地方：一是 token 是否过期，需要重新登录；二是环境变量里是否设置了和认证冲突的变量。比如CODEX_API_KEY如果存在，Codex 会优先读取它，登录态就会被"覆盖"。
清理方法很简单：把相关 API Key 环境变量临时清掉，重新codex login，确认能正常访问后再按需恢复环境变量。记住一个原则：CLI 的认证信息最好保持单一来源，不要既走登录 token 又塞环境变量，逻辑越简单越不容易出错。
5.3 Windows 桌面版的问题速查
课程里几个同学遇到过桌面版打不开或闪退，我整理成一张速查表：
| 现象 | 常见原因 | 解决方向 |
|---|---|---|
| 安装后双击没反应 | 缺少系统运行库依赖 | 补齐运行库后重试 |
| 启动后一直停在登录页 | 本地网络策略限制 | 调整系统代理设置，让流量正常出入 |
| 对话时突然断开 | 模型服务超时 | 查看日志，调大请求超时时间 |
如果照着处理还是不行，多半是安装包版本和系统位数不匹配。去官方下载页看最新版说明，选择对应架构的包重装一次。
5.4 关于国内接入的一些经验
"国内如何使用 Codex"这个问题基本每期都有学员问，我把它拆成两层说。第一层，Codex 本身是官方工具，注册、文档、使用方式都走官方公开渠道，认准官网和官方 GitHub 仓库就能避免很多弯路。第二层，模型服务层面，国内有大量可以正常注册和使用的合规服务商，比如 DeepSeek 对外开放的 API。把 Codex 的 provider 切换到这类服务商上，就能顺利完成训练和调用。整套配置过程不需要任何额外网络工具，也不需要做任何特殊设置，合规、稳定、可持续。
我个人的体会是，配置这类工具时，最忌讳的是在网上搜索并照抄一些来路不明的"加速方案"或"中转配置"。那些看起来"一步到位"的方案，往往改写了核心接口路径，反而破坏了服务的完整性和安全性，出了问题后还很难排查。老老实实走官方渠道，配合国内合规模型服务商，是最省心的做法。
最后再分享一点我的个人体会
整套课程跟下来，我最大的感受是：智能体应用的门槛真的不在算法，而在工程化和产品化。代码和配置都不难，跟着步骤走，两三天就能把一个能用的智能体跑起来。真正考验人的，是把需求描述清楚、把工具边界划定好、把异常情况想周全。Codex 在这套体系里扮演的角色，就像一个精力充沛但经验不足的团队成员——你得告诉它目标、给它趁手的工具、立好规矩，然后它会自己摸索着把事情干完。
如果你准备跟着这套实战课走一遍，最后给你三个切实建议：
- 别拿现成教程里的项目直接抄，选一个你自己工作里真实存在的重复性任务，比如整理下载目录、批量重命名截图、统计项目代码行数，越具体越好。
- 多故意制造几次失败。让智能体处理一个它没见过的文件类型，或者给它一个名称有冲突的目录，观察它是怎么分析、怎么尝试、怎么向你求助的。这个过程比写十个成功案例都长经验。
- 一定要读完
AGENTS.md层面的"任务说明书"逻辑。很多人忽略这个文件，但它决定了智能体是"指哪打哪的实习生"还是"想到哪算哪的随机程序"。任务边界写清楚了，后面不管用什么框架、什么平台，你都会是最从容的那个人。
