AI Agent 实战经验：Codex 与 DeepSeek 开发工作流踩坑总结

1. 从零上手 AI Agent：我踩过的坑和总结出的实战经验

AI Agent 这个词这两年火得不行，但真正在日常工作中把它用起来、用出效果的人其实没想象中那么多。我大概从两年前开始陆续把 AI Agent 引入到自己的开发流程里，从最早的 ChatGPT 对话式辅助，到后来用 Codex 做命令行代码生成，再到用 DeepSeek 做本地化推理和自动化任务编排，中间踩过的坑可以说能写一本小册子。这篇文章不是教程，也不是什么系统性指南，就是把我自己实际用下来觉得有价值的经验、教训和一些“早知道就好了”的细节整理出来，给正在入门或者准备深入用 AI Agent 的朋友做个参考。

不管你是刚听说 AI Agent 想试试水，还是已经在用 ChatGPT、Codex、DeepSeek 这些工具但总觉得“差点意思”，我相信下面这些内容都能帮你少走一些弯路。我会从整体思路、工具选型、实操配置、常见问题排查几个维度展开，尽量把每个决策背后的逻辑讲清楚，让你不仅知道怎么做，还知道为什么这么做。

2. AI Agent 到底是什么：先把概念理清楚再动手

2.1 别被术语吓到，Agent 本质就是“能自己干活的 AI”

很多人第一次听到 AI Agent 会觉得特别高大上，其实拆开看就很好理解。普通的 ChatGPT 对话是你问一句它答一句，它不会主动做任何事情。而 AI Agent 的核心区别在于：它能够根据你的目标，自主规划步骤、调用工具、执行操作，然后根据执行结果决定下一步做什么。打个比方，普通对话式 AI 像是一个顾问，你问他什么他答什么；而 AI Agent 更像是一个助理，你告诉他“帮我把这个项目的测试覆盖率提到 80%”，他会自己去读代码、找缺口、写测试、跑验证，中间不需要你一步步指挥。

这个“自主性”的程度不同，Agent 的复杂度也完全不同。最简单的 Agent 可能只是带工具调用的 ChatGPT，比如让它帮你查个天气、算个数学题。复杂一点的，像 Codex 这种命令行编程 Agent，它能直接在你的终端里读写文件、执行命令、跑测试。再往上，你可以用框架把多个 Agent 串联起来，做一个自动化的开发流水线。

2.2 主流架构其实就那几种，别被花哨的名字绕晕

市面上关于 AI Agent 架构的说法五花八门，但落到实际使用中，你真正需要理解的核心模式就那么几种。第一种是单 Agent 加工具调用，这也是最常见的形态。ChatGPT 的插件系统、Codex 的命令行模式、DeepSeek 的 API 调用，本质上都是这个模式：一个模型加上若干可调用的工具函数。第二种是多 Agent 协作，比如一个 Agent 负责写代码，另一个负责审查，还有一个负责跑测试，它们之间通过消息传递来协调。第三种是带记忆的持续 Agent，它能记住之前的交互历史，在长时间跨度上保持上下文一致性。

对于绝大多数开发者来说，我建议从第一种模式开始。原因很简单：单 Agent 加工具调用的调试成本最低，出问题了容易定位，而且大部分日常任务用这个模式就足够了。多 Agent 协作听起来很酷，但实际用起来你会发现 Agent 之间的通信开销、状态同步、错误传播这些问题会让复杂度指数级上升。我自己的经验是，除非你的任务确实需要多个专业角色分工，否则不要轻易上多 Agent 架构。

2.3 为什么我最终选择了 Codex + DeepSeek 的组合

工具选型这块我折腾了很久，试过不少方案，最后稳定下来的组合是 Codex 做命令行编程助手，DeepSeek 做本地推理和批量任务处理。选 Codex 的理由很直接：它跟 Git 的集成做得非常自然，能在终端里直接完成代码生成、修改、提交这一整套流程，不需要在编辑器和终端之间来回切换。而且 Codex 对项目上下文的理解能力比较强，它能读取你项目里的文件来推断你的代码风格和依赖关系。

选 DeepSeek 的原因则不太一样。一方面它在中文场景下的表现确实不错，另一方面它的 API 调用成本相对可控，适合做那些需要大量调用的自动化任务。比如我经常用它来批量生成测试用例、做代码注释补全、或者对日志做结构化分析。这两个工具配合起来，基本覆盖了我日常开发中需要 AI 辅助的大部分场景。

注意：工具选型没有绝对的最优解，关键看你的实际需求。如果你主要做前端开发，可能 ChatGPT 加浏览器的组合更顺手；如果你做数据科学，可能 Jupyter 加 DeepSeek 的搭配更合适。不要因为别人说某个工具好就盲目跟风，先想清楚自己最常做的任务是什么。

3. 环境搭建与基础配置：这些细节决定了你能不能跑起来

3.1 Git 安装与配置：看似简单但坑最多的一步

Git 的安装本身不复杂，Windows 上直接下载安装包一路下一步就行，Mac 用 Homebrew 一行命令搞定。但配置环节才是真正容易出问题的地方。我见过太多人装完 Git 之后直接就开始用，结果提交记录里全是乱码、换行符问题、SSH 认证失败各种毛病。

首先说换行符的问题。Windows 和 Unix 系统对换行符的处理不一样，如果不配置好，跨平台协作时会出现整个文件都被标记为修改的情况。我的建议是在安装 Git 后第一件事就是设置：

git config --global core.autocrlf input

这个配置在 Mac 和 Linux 上直接用，Windows 上建议设为true。具体选哪个取决于你的团队协作环境，如果团队里 Windows 和 Mac 都有，统一用input加.gitattributes文件来管理是最稳妥的。

SSH 认证失败是另一个高频问题。典型报错是Permission denied (publickey)，原因通常是你本地没有生成 SSH key，或者生成了但没有添加到 SSH Agent 里。完整的操作流程是这样的：

# 生成 SSH key，邮箱换成你自己的 ssh-keygen -t ed25519 -C "your_email@example.com" # 启动 SSH Agent eval "$(ssh-agent -s)" # 添加私钥 ssh-add ~/.ssh/id_ed25519 # 查看公钥内容，复制到代码托管平台 cat ~/.ssh/id_ed25519.pub

这里有个细节很多人会忽略：如果你用的是 Windows 的 PowerShell 而不是 Git Bash，eval "$(ssh-agent -s)"这个命令是不生效的，需要用Start-Service ssh-agent来启动服务。我自己在这上面浪费过不少时间，后来养成了在 Git Bash 里操作的习惯。

3.2 Codex 安装与首次登录：别被报错吓退

Codex 的安装方式取决于你用的平台。如果是通过 npm 安装，命令是：

npm install -g @openai/codex

安装完成后第一次运行codex会提示你登录。这里有个常见问题：如果你之前用过 ChatGPT 的账号体系，可能会遇到The 'gpt-6.1-sol' model is not supported when using codex with a chatgpt account这类报错。这个问题的根源是 Codex 的模型支持和 ChatGPT 账号的权限体系不完全一致。解决办法通常是检查你的账号是否有 Codex 的访问权限，或者改用 API Key 的方式登录。

另一个高频报错是无法加载 config.toml。Codex 的配置文件默认在~/.codex/config.toml，如果这个文件不存在或者格式有问题，就会导致对话无法继续。我的建议是首次使用时手动创建这个文件，内容至少包含：

model = "codex-mini-latest" provider = "openai"

如果你要用 DeepSeek 作为后端，配置会稍微复杂一些，需要指定自定义的 API endpoint 和模型名称。具体配置取决于 DeepSeek 提供的接口格式，建议参考官方文档来写。

3.3 DeepSeek 的接入方式与注意事项

DeepSeek 的接入主要有两种方式：直接用官方 API，或者通过兼容 OpenAI 接口的第三方平台。官方 API 的稳定性最好，但需要处理 rate limit 和 token 计费的问题。第三方平台可能在价格上有优势，但稳定性和数据安全性需要自己评估。

我在用 DeepSeek 做批量任务时总结了几条经验。第一，一定要设置合理的超时和重试机制，因为长文本生成时偶尔会遇到响应超时的情况。第二，对于结构化输出的任务，在 prompt 里明确要求 JSON 格式，并且在代码里做解析容错。第三，token 消耗要提前估算，特别是做大批量处理时，最好先用小样本测试一下平均消耗再决定是否全量跑。

提示：DeepSeek 的 API 调用如果遇到连接问题，先检查你的网络环境是否正常，然后确认 API Key 是否有效、余额是否充足。大部分连接类报错都是这几个原因导致的。

4. 实操核心环节：我是怎么把 AI Agent 用起来的

4.1 用 Codex 做日常代码生成和重构

Codex 最让我满意的场景是代码重构。比如你有一个函数写得特别长，想拆成几个小函数，传统做法是手动复制粘贴再调整，费时费力还容易出错。用 Codex 的话，你只需要在终端里描述你的需求：

codex "把 src/utils/parser.js 里的 parseConfig 函数拆分成三个独立的函数，分别负责读取、验证和转换"

Codex 会读取文件内容，理解函数逻辑，然后生成拆分后的代码。但这里有个关键点：不要直接让它写入文件。我的习惯是先用--dry-run模式看看它打算怎么改，确认没问题再实际执行。这个习惯帮我避免了好几次因为模型理解偏差导致的代码破坏。

另一个常用场景是写测试。你可以让 Codex 根据现有代码生成单元测试，但要注意它生成的测试往往覆盖的是“正常路径”，边界条件和异常情况需要你自己补充。我的做法是让 Codex 先生成一版，然后我手动补充边界测试，最后再让它检查一遍有没有遗漏。

4.2 用 DeepSeek 做批量文本处理和数据分析

DeepSeek 在我手里的主要用途是批量处理那些“需要理解语义但规则不好写”的任务。举个例子，我有一批用户反馈的日志，需要按问题类型分类。用正则表达式写规则的话，覆盖不全还容易误判。用 DeepSeek 的话，我只需要把日志内容传进去，让它输出分类标签：

import requests def classify_log(log_text): prompt = f"""请将以下用户反馈分类为：性能问题、功能缺陷、使用咨询、其他。 只输出分类结果，不要解释。 反馈内容：{log_text} """ response = requests.post( "https://api.deepseek.com/v1/chat/completions", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "model": "deepseek-chat", "messages": [{"role": "user", "content": prompt}], "temperature": 0 } ) return response.json()["choices"][0]["message"]["content"].strip()

这段代码的关键在于temperature=0，它让输出尽可能确定，避免同一输入得到不同分类结果。另外 prompt 里明确要求“只输出分类结果”，这样后续处理时不需要再做额外的文本清洗。

批量处理时要注意控制并发数。我一开始图快，开了 50 个并发请求，结果触发限流不说，还有不少请求超时失败。后来改成 5 到 10 个并发，加上失败重试，整体吞吐量反而更高。

4.3 把 AI Agent 接入 Git 工作流

Git 和 AI Agent 的结合是我觉得最有价值的一个实践方向。具体来说，我配置了一套自动化流程：每次提交代码前，让 Codex 自动检查 diff 内容，生成提交信息，并且对明显的代码问题给出提示。

实现方式是通过 Git 的 pre-commit hook。在.git/hooks/pre-commit里写一个脚本，调用 Codex 来分析暂存区的改动：

#!/bin/bash # 获取暂存的 diff DIFF=$(git diff --cached) # 调用 Codex 生成提交信息建议 SUGGESTION=$(codex "根据以下代码改动生成一条简洁的提交信息，格式为 type: description" <<< "$DIFF") echo "建议的提交信息：$SUGGESTION"

这个 hook 不会自动提交，只是给出建议，最终提交信息还是由我来决定。这样既享受了 AI 的便利，又保留了人工审核的环节。实测下来，这个流程帮我省了不少写提交信息的时间，而且生成的提交信息质量比我随手写的要规范得多。

注意：pre-commit hook 里的 AI 调用会增加提交的耗时。如果你对提交速度敏感，可以把这个检查放到 pre-push 阶段，或者只在改动较大时才触发。

4.4 用 AI Agent 辅助 Django 项目开发

我之前用 AI Agent 辅助开发过一个 Django 项目，积累了一些特定于 Web 框架的经验。Django 项目的特点是文件多、层次分明，这对 AI Agent 来说既是优势也是挑战。优势在于项目结构规范，Agent 容易理解代码组织方式；挑战在于跨文件修改时，Agent 需要同时理解多个文件的关联关系。

我的做法是给 Codex 提供一个项目结构说明文件，放在项目根目录下，内容大致包括：各个 app 的职责、模型之间的关系、常用的工具函数位置。这样每次让 Codex 做修改时，它会先读这个文件来建立上下文。实测下来，有了这个说明文件之后，Codex 生成的代码跟项目现有风格的匹配度明显提高。

另一个经验是关于数据库迁移的。Django 的 migration 文件是自动生成的，但 AI Agent 在修改模型后经常会忘记提醒你生成迁移。我的做法是在 prompt 里明确要求：“修改模型后，提醒我运行 makemigrations 和 migrate”。这个小小的提示词调整，帮我避免了好几次“改了模型但数据库没同步”的低级错误。

5. 常见问题与排查技巧实录

5.1 ChatGPT 连接类问题的排查思路

ChatGPT 用不了、一直在重新连接、报错 10013 这类问题，排查顺序应该是这样的：先确认网络环境是否正常，然后检查账号状态是否正常，最后看是不是客户端版本太旧。大部分连接问题都是网络层面的，换个网络环境或者稍等几分钟再试通常就能解决。

如果是Windows 10 ChatGPT 打不开的情况，常见原因是系统代理设置有问题，或者防火墙拦截了相关请求。可以尝试在命令提示符里运行netsh winsock reset重置网络栈，然后重启电脑。这个操作解决过我遇到的大部分客户端连接异常。

5.2 Codex 配置报错的快速定位方法

Codex 的报错信息有时候比较隐晦，我总结了一个快速定位的流程。首先看报错里有没有提到具体的配置文件路径，如果有，直接去检查那个文件的格式和内容。其次看报错是否跟模型名称有关，如果是，检查你的 config.toml 里 model 字段的值是否跟你的账号权限匹配。最后看是不是 provider 配置的问题，特别是当你用第三方 API 时，endpoint 和认证方式很容易配错。

cc switch local proxy failed while handling codex endpoint /responses这类报错通常跟本地代理配置有关。如果你没有主动设置代理，检查一下环境变量里有没有HTTP_PROXY或HTTPS_PROXY的残留配置。这些变量有时候会被其他软件设置，导致 Codex 的请求被错误地转发。

5.3 DeepSeek 使用中的典型问题

DeepSeek 最常见的问题是响应超时和输出截断。超时问题可以通过增加 timeout 参数和重试机制来缓解。输出截断则通常是因为 max_tokens 设置得太小，需要根据你的任务类型调整这个值。对于代码生成任务，我一般设 2048 到 4096；对于文本分析任务，1024 通常就够了。

另一个值得注意的问题是 DeepSeek 对某些特定格式的输入比较敏感。比如输入里包含大量特殊符号或者嵌套的 JSON 时，模型可能会输出格式混乱的结果。我的应对方法是在 prompt 里明确要求输出格式，并且在代码里做严格的解析和校验。如果解析失败，就把原始输出记录下来人工检查，而不是直接丢弃。

5.4 常见问题速查表

6. 一些让我少走弯路的实操心得

6.1 提示词写得好，Agent 干活少烦恼

用了这么久 AI Agent，我最大的体会是：提示词的质量直接决定了输出质量。同样一个任务，模糊的指令和精确的指令得到的结果可能天差地别。我的经验是，好的提示词应该包含四个要素：任务描述、输入说明、输出格式要求、约束条件。

举个例子，让 Agent 帮你写一个函数。差的提示词是“写一个排序函数”。好的提示词是“用 Python 写一个快速排序函数，输入是一个整数列表，返回排序后的新列表，不要修改原列表，要求处理空列表和单元素列表的情况，代码风格遵循 PEP 8”。后者虽然长，但 Agent 一次就能生成符合要求的代码，省去了反复沟通的成本。

6.2 永远保留人工审核环节

不管 AI Agent 看起来多智能，我始终坚持一个原则：关键操作必须有人工审核。代码提交前要 review，数据库操作前要确认，文件删除前要备份。这不是对 AI 不信任，而是对自己负责。我见过太多因为过度信任 AI 输出而导致的事故，有些代价还挺大的。

具体做法上，我会把 AI Agent 的操作分成三类：只读操作（如查询、分析）可以直接执行；写入操作（如生成文件、修改代码）需要我确认；危险操作（如删除、覆盖、部署）必须我手动执行。这个分类标准帮我建立了一个安全的使用边界。

6.3 上下文管理是长期使用的关键

AI Agent 的上下文窗口是有限的，这意味着你不能指望它记住所有历史交互。对于长期项目，我建议维护一个“项目知识文件”，把重要的背景信息、约定、常用命令都写进去。每次开始新的对话时，先把这个文件的内容提供给 Agent，让它快速建立上下文。

这个做法看起来有点笨，但实际效果很好。我的项目知识文件里包含了：项目架构说明、代码规范、常用命令、已知问题列表。有了这些信息，Agent 生成的代码和建议的准确率明显提升。而且这个文件本身也是很好的项目文档，新成员加入时可以直接参考。

6.4 成本控制要从第一天就重视

AI Agent 的使用成本很容易被低估。单次调用看起来不贵，但如果你把它接入到自动化流程里，每天跑几百上千次，月底账单可能会让你吃惊。我的做法是：第一，给每个自动化任务设置预算上限，超过就暂停并通知我；第二，定期审查调用日志，找出那些消耗大但价值低的任务并优化；第三，对于简单的分类、提取任务，优先用规则或小模型，把大模型留给真正需要理解能力的场景。

提示：很多平台提供用量监控和告警功能，花十分钟配置一下，能帮你避免很多不必要的支出。

6.5 保持学习，但不要盲目追新

AI 领域的变化速度确实很快，几乎每周都有新工具、新框架出现。我的态度是：保持关注，但不要盲目追新。新工具出来先看看它解决了什么问题，跟自己当前用的方案比有没有实质性优势，再决定要不要切换。频繁切换工具的成本很高，而且很容易陷入“一直在学新工具但什么都没做深”的困境。

我自己的节奏是：每季度花半天时间集中了解一下这段时间出现的新东西，筛选出值得试用的，然后用一个小项目实际跑一下。只有真正在实战中验证过确实更好的，才会纳入我的常规工具箱。这个节奏让我既能跟上技术发展，又不会被各种新概念牵着鼻子走。

6.6 关于 AI Agent 学习路线的个人建议

如果你刚开始接触 AI Agent，我建议的学习路径是这样的：先用 ChatGPT 或 DeepSeek 的对话功能熟悉基本的交互方式，理解模型的能力边界。然后尝试用 API 做简单的自动化任务，比如批量文本处理。接着学习工具调用的概念，让 Agent 能执行实际操作。最后再考虑多 Agent 协作和复杂工作流编排。

这个路径的好处是每一步都有明确的产出，你能清楚地感受到自己在进步。不要一上来就啃框架文档、搭复杂架构，那样很容易受挫。我见过不少人一开始热情满满要搭一个全自动开发流水线，结果卡在环境配置就放弃了。从简单场景开始，逐步增加复杂度，才是可持续的学习方式。

6.7 团队协作中的 AI Agent 使用规范

如果你在团队里推广 AI Agent，有几个点需要提前考虑。首先是代码风格的一致性，不同人用 AI 生成的代码风格可能差异很大，需要制定统一的规范。其次是知识共享，把好用的提示词、配置、工作流整理成文档，让团队成员都能受益。最后是安全边界，明确哪些操作可以用 AI 辅助，哪些必须人工完成。

我们团队的做法是维护一个共享的提示词库，每个人都可以往里贡献自己觉得好用的提示词。同时定期做经验分享，让大家交流使用心得和踩过的坑。这个机制运行下来效果不错，新成员上手速度明显加快，整体效率也有提升。

6.8 我目前的工作流长什么样

最后分享一下我现在的日常工作流，给大家一个参考。早上到工位后，先用 Codex 快速过一遍昨天的代码改动，让它生成一个变更摘要。然后处理邮件和消息，期间遇到需要查资料的问题直接问 ChatGPT。写代码时，Codex 常驻终端，遇到不确定的 API 用法或者想重构的代码块随时调用。批量数据处理任务用 DeepSeek 跑，结果自动保存到指定目录。提交代码前，pre-commit hook 会自动检查并生成提交信息建议。

这套流程不是一天搭起来的，是用了两年时间慢慢磨合出来的。中间换过工具、调整过配置、踩过不少坑，但整体方向是越来越顺。AI Agent 对我来说已经不是一个“新鲜玩意”，而是实实在在提升效率的工具。希望我的这些经验能帮你少走一些弯路，更快地找到适合自己的使用方式。