1. 从零上手 AI Agent我踩过的坑和攒下的经验AI Agent 这个词这两年火得不行但真正动手搭过、用过、调过的人都知道它跟“聊天机器人”完全是两码事。我最早接触 AI Agent 是在一个内部工具项目里当时的需求很简单让模型自己读代码仓库、改 bug、跑测试、提 PR。听起来很酷实际做起来才发现光是把环境跑通就花了我整整两天。后来陆续试了 ChatGPT、Codex、DeepSeek 这几条路线也踩了不少坑比如 Codex 接入 DeepSeek 时端点报错、Git 配置不对导致拉取失败、模型版本不支持等等。这篇文章就把我这些经验整理出来从环境准备到 Agent 搭建再到常见问题排查尽量讲透。不管你是刚听说 AI Agent 想练手还是已经在做 AI Agent 开发但卡在某个环节应该都能找到点有用的东西。先说清楚 AI Agent 到底是什么。你可以把它理解成一个“会自己想办法完成任务”的程序你给它一个目标比如“把这个项目的单元测试覆盖率提到 80%”它会自己拆解步骤、调用工具、读文件、写代码、跑命令遇到错误还会自己调整。这跟传统的“你问一句它答一句”的 ChatGPT 有本质区别。ChatGPT 更像一个知识渊博的顾问而 AI Agent 更像一个能动手干活的实习生。当然这个实习生有时候会犯迷糊所以你得知道怎么带它。我下面会按四个部分来讲第一是整体设计思路为什么我选这些工具和架构第二是核心细节包括 Git、Codex、DeepSeek 的配置要点第三是完整实操流程从零搭一个能跑的小 Agent第四是常见问题和排查技巧。每一部分我都会尽量给出具体的命令、参数和判断依据而不是泛泛而谈。2. 整体设计与工具选型为什么这么搭2.1 先想清楚 Agent 的边界在哪里很多人一上来就想搭一个“全能 Agent”结果往往是什么都做不好。我的经验是先明确 Agent 的职责边界。比如你是要它做代码审查、自动修 bug、还是做数据分析不同任务对工具链的要求完全不同。代码类 Agent 必须能访问文件系统和 Git数据分析类 Agent 则需要能跑 Python 和读表格。我见过一个团队花了两周搭了个“通用 Agent”最后发现连最基本的代码检索都做不稳原因就是工具太多、提示词太杂模型根本不知道该用哪个。所以我的建议是从单一场景切入。比如先做一个“自动修复 lint 错误”的 Agent任务明确、反馈及时、容易验证。等这个跑通了再逐步扩展能力。这样你也能快速积累对模型行为的直觉知道它在什么情况下会出错。2.2 模型选型ChatGPT、Codex、DeepSeek 怎么选模型是 Agent 的大脑选错了后面全是坑。我实际用下来这三条路线各有适用场景。ChatGPT 系列包括通过 API 调用的 GPT 模型优势在于通用能力强、指令遵循好适合做需要理解复杂语义的任务比如代码审查、文档生成。但它的缺点是贵而且国内访问需要处理网络问题这里不展开懂的都懂。另外 ChatGPT 的对话界面和 API 是两套东西很多人搞混以为买了 Plus 就能随便调 API其实不是。Codex 是专门为代码场景优化的它在代码补全、函数生成、跨文件理解上表现很好。我一开始以为 Codex 就是个代码版的 ChatGPT后来发现它在处理仓库级上下文时确实更强。但 Codex 的坑也不少比如模型版本限制、端点配置复杂。我遇到过the gpt-5.6-sol model is not supported when using codex with a chatgpt acc这个报错折腾了半天才发现是账号类型和模型不匹配。DeepSeek 是我最近用得比较多的性价比高而且国内访问稳定。DeepSeek 的 API 兼容 OpenAI 格式所以很多工具可以直接接。但要注意DeepSeek 有多个版本比如 DeepSeek Coder 和 DeepSeek Chat做 Agent 一般用 Coder 版本更合适。另外网上有些关于“DeepSeek 破甲无限制词”的说法我建议不要碰一来不合规二来实际效果也不稳定正经做项目没必要走这种偏门。我的选型逻辑是如果任务以代码为主、预算有限优先 DeepSeek如果需要强通用推理、且能接受成本用 ChatGPT如果团队已经在用 Codex 生态那就继续用 Codex但要做好版本和端点的兼容测试。2.3 工具链Git 是绕不开的基础不管你做哪类 Agent只要涉及代码Git 就是必须的。我见过不少新手卡在 Git 安装和配置上比如git安装、git安装教程这些搜索词热度一直很高说明确实有人被卡住。Git 的核心作用不只是版本控制它还是 Agent 获取代码上下文、提交修改、回滚错误的基石。你可以让 Agent 通过 Git 命令读取历史提交、对比差异、创建分支这些能力直接决定了 Agent 能不能“看懂”项目。我的建议是在搭 Agent 之前先把 Git 环境弄稳。具体包括安装 Git、配置用户名和邮箱、设置默认分支名、配置 SSH 或 token 认证。这些步骤看起来基础但一旦出错后面 Agent 跑起来会莫名其妙失败。比如git commit --amend用不好可能会把 Agent 的修改搞乱diea创建新项目拉取git这种操作如果认证没配好直接卡在拉取阶段。2.4 架构从“单 Agent”到“Agent 中台”刚开始别想着搞什么“AI Agent 中台”那是团队规模上来之后才需要考虑的。个人或小团队起步一个单 Agent 加几个工具就够了。典型的架构是一个主循环负责接收任务、调用模型、解析输出、执行工具、把结果喂回模型直到任务完成或达到最大轮次。工具层包括文件读写、Shell 执行、Git 操作、HTTP 请求等。记忆层可以用简单的文件存储或向量数据库但初期用文件就够了。我试过一上来就上向量数据库和复杂编排结果调试成本极高一个环节出错要查半天。后来退回到最简架构反而跑得更稳。所以我的经验是先跑通最小闭环再逐步加能力。3. 核心细节解析Git、Codex、DeepSeek 的配置要点3.1 Git 安装与配置别小看这几步Git 安装本身不难Windows 下下载安装包一路下一步就行Mac 用 Homebrew 或者直接装 Xcode Command Line Tools。但配置才是关键。我列一下我每次新环境都会做的几件事。第一配置用户信息。命令是git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条必须配否则 commit 会失败。我见过有人用 Agent 自动提交时因为没配邮箱直接报错查了半天。第二设置默认分支名。现在主流是 main但老版本 Git 默认是 master。可以用git config --global init.defaultBranch main第三配置认证。如果用 HTTPS建议用 token 而不是密码如果用 SSH需要生成密钥并添加到平台。SSH 的好处是 Agent 调用时不用交互输入密码更适合自动化。生成命令ssh-keygen -t ed25519 -C 你的邮箱然后把公钥加到代码托管平台。测试连接ssh -T gitgithub.com如果返回欢迎信息就说明通了。第四注意git commit --amend的使用。这个命令会修改最近一次提交Agent 在自动修复时可能会用到。但要注意如果提交已经推送到远程amend 后再推送需要 force push这在团队协作中很危险。我的做法是让 Agent 尽量用新提交而不是 amend除非明确知道自己在做什么。3.2 Codex 安装与接入版本和端点是两大坑Codex 的安装方式取决于你用哪个版本。如果是命令行工具一般通过 npm 或官方安装包。我遇到最多的问题是模型版本不匹配。比如报错the gpt-5.6-sol model is not supported when using codex with a chatgpt acc意思是你用的账号类型不支持这个模型。解决办法是换模型或者换账号类型。具体怎么查支持哪些模型可以看官方文档或者用最小请求测试。另一个常见问题是端点配置。Codex 默认走 OpenAI 的端点但如果你想接 DeepSeek就需要改 base URL。我试过codex接入deepseek配置大概是export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEY你的 DeepSeek key然后 Codex 调用时就会走 DeepSeek。但要注意不是所有 Codex 功能都兼容有些高级特性可能只支持原生 OpenAI 端点。我实测下来基础的代码生成和补全没问题但涉及特定工具调用时可能会报错。还有cc switch local proxy failed while handling codex endpoint /responses这类报错通常是本地代理配置有问题。如果你用了代理工具检查端口和路径是否正确。我的建议是如果不需要代理直接连官方端点最稳如果需要确保代理规则只针对必要流量别把本地请求也代理了。3.3 DeepSeek API 调用便宜但要注意细节DeepSeek 的 API 调用跟 OpenAI 很像基本可以直接替换。示例from openai import OpenAI client OpenAI( api_key你的 DeepSeek key, base_urlhttps://api.deepseek.com/v1 ) response client.chat.completions.create( modeldeepseek-coder, messages[ {role: user, content: 写一个 Python 函数计算斐波那契数列} ] ) print(response.choices[0].message.content)注意模型名要写对DeepSeek 有deepseek-chat和deepseek-coder等。做 Agent 一般用 coder 版本。另外 DeepSeek 的计费方式是按 token具体价格看官网。我建议在 Agent 里加一个 token 统计避免跑飞了账单爆炸。关于deepseek部署如果你要本地部署需要显卡和相应环境成本不低。个人练手直接用 API 更划算。deepseek导出一般指导出对话记录或数据API 调用的话自己存就行。3.4 ChatGPT 使用中的常见问题ChatGPT 相关的问题很多比如chatgpt payment was not approved是支付被拒通常是卡的问题unable to load sign-in requirements chatgpt是登录加载失败可能跟网络或浏览器缓存有关无法加载此 chatgpt 对话也是类似。chatgpt failed to start. 该进程没有程序包标识符怎么解决这种是 Windows 应用的问题一般重装或修复应用包能解决。我的经验是ChatGPT 的网页版和 API 要分开对待。网页版问题多跟网络和账号有关API 问题多跟 key 和额度有关。做 Agent 开发重点保证 API 可用就行网页版偶尔抽风不影响。4. 实操过程从零搭一个能跑的小 Agent4.1 环境准备清单我列一下我搭 Agent 时的最小环境Python 3.10 以上Git 已安装并配置好一个可用的模型 API keyDeepSeek 或 OpenAI一个代码编辑器VS Code 就行基本的命令行操作能力不需要一开始就上 Docker、Kubernetes 这些除非你要部署到服务器。4.2 第一步初始化项目并接入 Git先建一个空目录初始化 Gitmkdir my-agent cd my-agent git init然后创建一个简单的 Python 文件比如agent.py。接着配置远程仓库如果需要git remote add origin gitgithub.com:你的用户名/my-agent.git这里如果 SSH 没配好会报权限错误。回去检查 3.1 的步骤。4.3 第二步写一个最小 Agent 循环核心逻辑就是读任务 - 调模型 - 解析输出 - 执行工具 - 把结果喂回模型。我写一个简化版import subprocess from openai import OpenAI client OpenAI(api_key你的key, base_urlhttps://api.deepseek.com/v1) def run_command(cmd): result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue) return result.stdout result.stderr def agent_loop(task, max_turns5): messages [{role: user, content: task}] for i in range(max_turns): response client.chat.completions.create( modeldeepseek-coder, messagesmessages ) reply response.choices[0].message.content print(f第 {i1} 轮模型输出{reply}) # 简单判断如果模型输出包含命令就执行 if bash in reply: cmd reply.split(bash)[1].split()[0].strip() output run_command(cmd) messages.append({role: assistant, content: reply}) messages.append({role: user, content: f命令输出{output}}) else: break return reply agent_loop(查看当前目录下的文件列表)这个例子很粗糙但能跑通基本流程。实际项目中你需要更严谨的输出解析比如用 JSON 格式约束模型输出避免它乱写命令。4.4 第三步加入 Git 操作能力让 Agent 能提交代码def git_commit(message): run_command(git add .) run_command(fgit commit -m {message})但要注意Agent 自动提交前最好先检查 diff避免提交不该提交的文件。我一般会让 Agent 先跑git status和git diff确认后再提交。4.5 第四步测试与迭代跑几个简单任务比如“创建一个 README 文件并提交”。观察 Agent 的行为看它是否按预期执行。如果出错看是模型输出格式问题还是工具执行问题。我一开始的 Agent 经常把命令写在非代码块里导致解析失败后来加了更严格的提示词才稳定。5. 常见问题与排查技巧实录5.1 模型相关报错速查报错信息可能原因解决办法the gpt-5.6-sol model is not supported账号类型与模型不匹配换模型或换账号cc switch local proxy failed本地代理配置错误检查代理端口和规则unable to load sign-in requirements网络或缓存问题清缓存、换网络chatgpt payment was not approved支付方式被拒换支付方式无法加载此 chatgpt 对话对话数据异常新建对话或清缓存5.2 Git 相关坑git commit --amend后 force push 导致队友代码丢失。建议 Agent 少用 amend。拉取代码时认证失败。检查 SSH key 或 token 是否过期。分支名不一致导致推送失败。统一用 main。5.3 Agent 行为异常排查如果 Agent 反复执行同一个命令可能是提示词里没限制轮次或者模型陷入了循环。解决办法是加最大轮次限制并在提示词里明确“如果任务完成就输出 DONE”。如果 Agent 执行了危险命令比如rm -rf一定要在工具层加白名单或确认机制。我吃过这个亏幸好是在测试环境。5.4 性能与成本控制Agent 跑起来 token 消耗很快尤其是多轮循环。我的做法是设置最大轮次、限制单次输出长度、用更便宜的模型做简单任务。另外可以加缓存相同请求不重复调模型。6. 一些个人体会和后续扩展方向搭 Agent 这件事最难的不是写代码而是理解模型的“脾气”。它有时候很聪明有时候又很固执。我的经验是提示词要写得像给实习生交代任务目标明确、步骤清晰、边界清楚。别指望它自己悟。后续如果想扩展可以加记忆功能让 Agent 记住之前的操作也可以加多 Agent 协作一个负责写代码一个负责审查。但这些都要在单 Agent 跑稳之后再考虑。我见过太多项目死在“贪多嚼不烂”上。最后分享一个小技巧每次 Agent 跑完把它的操作日志存下来定期回顾。你会发现很多问题其实是重复的改一次提示词就能避免一大类错误。这个习惯帮我省了不少时间。