1. 从一份AI 日报的标题说起为什么值得认真拆解看到AI 日报 | 2026-09-24这个标题很多人的第一反应是——这不就是个日期归档吗但如果你真的在 AI 工具链这个圈子里待过一段时间就会明白一份日报的价值从来不在于它写了什么惊天动地的大事而在于它把当天散落在各个角落的碎片信息按一条主线串了起来。而这条主线从关键词和热搜词来看非常清晰——AI 编程助手工具链的落地实践具体来说就是 Codex、Claude Code、AGENTS.md、LiteLLM 这几个东西怎么配合着用。我自己从 2024 年开始就在日常开发中重度使用各类 AI 编程工具从最早的 Copilot 到后来的 Cursor、Claude Code、Codex CLI踩过的坑可以说能写一本书。所以当我看到这份日报的关键词组合时第一反应是这几个词放在一起说明写日报的人正在经历一个非常典型的阶段——从单个工具试用过渡到多工具协同 本地模型接入 统一网关管理的工程化阶段。这个阶段的核心痛点是什么我用一句话概括你不再满足于某个工具能不能用而是开始关心这些工具怎么在一个统一的配置体系下稳定协作并且能灵活切换底层模型。AGENTS.md 解决的是项目级 AI 行为约定的问题LiteLLM 解决的是多模型统一接口的问题Codex 和 Claude Code 则是两个不同风格的前端交互入口。把它们串起来就是一套完整的个人 AI 开发工作流。这篇文章我会围绕这几个核心组件把它们的定位、配置方式、协作逻辑、以及我在实际使用中踩过的坑尽可能完整地讲清楚。不管你是刚接触 AI 编程助手的新手还是已经在用但总觉得差点意思的老手应该都能从中找到一些可以直接抄作业的东西。提示本文涉及的所有工具配置均基于公开文档和通用实践具体版本行为可能随更新变化建议以官方最新说明为准。2. Codex 与 Claude Code两个入口的定位差异与选择逻辑2.1 它们到底解决的是同一类问题吗很多人把 Codex 和 Claude Code 当成竞品来看觉得选一个就行。但实际用下来我的判断是它们解决的是同一类问题AI 辅助编程但切入角度和工作方式有本质区别。Codex 这一系工具的核心设计理念是任务导向的代码生成与执行。你给它一个相对明确的任务描述它会尝试理解上下文、生成代码、甚至执行验证。它更像一个能动手的助手适合处理边界清晰的功能实现、脚本编写、bug 修复这类任务。Claude Code 则是对话式 项目感知的路子。它会读取你的项目结构、理解文件之间的关系然后在一个持续的对话上下文中帮你做修改。它的强项在于跨文件的重构、理解复杂代码库、以及需要多轮交互才能明确的需求。我举个实际例子你就明白了。有一次我需要给一个 Python 项目加一个 CLI 子命令涉及参数解析、配置文件读取、日志输出三块改动。用 Codex 的话我会把需求拆成三段分别描述它分别生成我再手动整合。用 Claude Code 的话我直接说给这个项目加一个 xxx 子命令参考现有的 yyy 命令的结构它会自己去读现有代码然后一次性给出协调好的改动。所以选择逻辑很简单场景推荐工具原因单文件功能实现Codex任务边界清晰生成效率高跨文件重构Claude Code需要项目级上下文理解快速脚本编写Codex不需要读整个项目理解陌生代码库Claude Code对话式探索更自然批量相似修改两者皆可看具体交互习惯2.2 安装环节最容易卡住的地方关于安装网上教程一大堆但我要说的是那些教程里不会告诉你的坑。Codex 的安装表面上看就是一条命令的事但实际卡人的地方在于运行环境的前置依赖。很多人在 Windows 上直接跑安装命令结果报一堆路径相关的错误。我的建议是如果你在 Windows 上优先考虑在 WSL 环境里装能省掉大量路径和权限相关的麻烦。这不是说 Windows 原生不能跑而是原生环境下的问题排查成本明显更高。Claude Code 的安装相对顺滑但有一个高频问题值得单独说订阅权限相关的报错。热搜词里出现了your organization has disabled claude subscription access for claude code这类信息说明不少人在企业或团队环境下遇到了访问限制。这种情况通常不是安装本身的问题而是账号权限配置的问题。遇到这类提示首先要确认的是你的账号类型和所在组织的策略设置而不是反复重装。还有一个被问得很多的点Claude Code 能不能调用本地模型。答案是能但需要通过中间层做协议转换。这就引出了后面要讲的 LiteLLM。热搜词里claude code 调用 lmstudio 的本地模型这个组合本质上就是Claude Code → LiteLLM → LM Studio 本地模型这样一条链路。2.3 安装完成后的第一件事不是写代码我见过太多人装完工具就迫不及待地开始让 AI 写业务代码结果体验很差然后得出结论这工具不行。问题出在哪出在没有做项目级的上下文配置。这就必须提到 AGENTS.md 了。这个文件的作用简单说就是告诉 AI 助手在这个项目里你应该遵守什么规则。它包括但不限于代码风格约定、目录结构说明、常用命令、禁止事项、技术栈信息。你可以把它理解成给新入职同事看的那份项目说明文档只不过读者是 AI。没有这份文档AI 每次都要从零猜测你的项目结构生成的东西自然容易跑偏。有了它AI 的首次响应质量会有肉眼可见的提升。一个最小可用的 AGENTS.md 大概长这样# 项目说明 ## 技术栈 - Python 3.11 FastAPI - 数据库PostgreSQL 15 - 测试pytest ## 目录结构 - src/ 核心代码 - tests/ 测试 - scripts/ 运维脚本 ## 代码规范 - 使用 type hints - 函数不超过 50 行 - 所有公开函数必须有 docstring ## 常用命令 - 启动make run - 测试make test - 格式化make fmt别小看这几十行它能让 AI 生成的代码从需要大改变成基本能用。这是我实测下来投入产出比最高的一个配置动作。3. AGENTS.md 的实战写法从能跑到好用的差距3.1 为什么大多数人的 AGENTS.md 写了等于没写我帮别人看过不少 AGENTS.md一个普遍问题是写得太抽象。比如请遵循良好的代码规范、注意代码质量这种话对 AI 来说等于没说因为它不知道你所谓的良好具体指什么。有效的 AGENTS.md 必须具体到可执行。对比一下无效写法使用合适的错误处理有效写法所有外部调用必须用 try/except 包裹异常统一用项目自定义的 AppError 抛出日志用 logger.error 记录无效写法保持代码风格一致有效写法字符串统一用双引号缩进 4 空格import 按标准库/第三方/本地三组排序组间空一行看出区别了吗前者是原则后者是规则。AI 需要的是规则不是原则。3.2 分层次组织内容的思路我的 AGENTS.md 一般分四层来写从不可变到可变依次排列第一层项目身份。一句话说清这个项目是干什么的技术栈是什么。这决定了 AI 的世界观。第二层硬性约束。绝对不能违反的规则比如不要修改 migrations 目录下的历史文件、不要引入新的第三方依赖除非明确要求。这些是红线。第三层风格约定。命名规范、代码组织方式、注释要求。这些影响生成代码的手感。第四层上下文提示。当前正在做的功能、已知的技术债、临时的特殊约定。这部分更新最频繁。这样分层的好处是当项目演进时你只需要改第四层前三层相对稳定。而且 AI 读取时也能分清优先级。3.3 一个容易被忽略的细节命令的准确性AGENTS.md 里写的常用命令必须是你亲自验证过能跑通的。我踩过一次坑在 AGENTS.md 里写了make test但实际上那个项目的 Makefile 里测试命令叫make tests多了个 s。结果 AI 每次建议我运行测试时都用错命令我还纳闷怎么老是报错查了半天才发现是配置文件的问题。这个教训告诉我AGENTS.md 里的每一条信息都要当成代码来对待写完要验证。宁可少写几条也不要写错的。另外如果你的项目有多个环境开发、测试、生产建议在 AGENTS.md 里明确说明当前 AI 应该假设自己在哪个环境工作。否则 AI 可能会生成一些只适合生产环境的配置在开发环境跑不起来。4. LiteLLM 作为统一网关多模型接入的核心枢纽4.1 为什么需要中间加一层先说清楚一个问题为什么不能直接让 Claude Code 或 Codex 连各种模型非要中间加个 LiteLLM原因有三个而且都是实际使用中会碰到的第一接口协议不统一。不同模型提供商的 API 格式、认证方式、参数命名都不一样。如果每个前端工具都要适配所有后端模型那就是 M×N 的适配工作量。有了 LiteLLM 这层前端只需要对接一种协议后端模型的差异由 LiteLLM 抹平。第二切换成本。今天想用 A 模型明天想试 B 模型如果没有统一网关你得改前端的配置甚至代码。有了 LiteLLM只改一个配置文件就行。第三可观测性。LiteLLM 提供了请求日志、用量统计、成本追踪这些能力。当你同时用好几个模型时这些数据对优化使用策略很有价值。热搜词里ccswitch 使用 litellm这个组合说的就是通过 LiteLLM 来做模型切换的实践。这个思路是对的因为 LiteLLM 的配置化切换确实比在每个工具里单独配置要清爽得多。4.2 最小可用的 LiteLLM 配置LiteLLM 的核心就是一个 YAML 配置文件。一个能跑起来的最小配置大概是这样model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-20250514 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-qwen litellm_params: model: openai/qwen2.5-coder api_base: http://localhost:1234/v1 api_key: dummy general_settings: master_key: sk-your-master-key litellm_settings: drop_params: true几个关键点解释一下model_name是你对外暴露的名字前端工具用这个名字来请求。litellm_params里的model是实际的后端模型标识格式是提供商/模型名。api_key用os.environ/前缀表示从环境变量读取这样避免把密钥写死在配置文件里。drop_params: true这个设置很重要。不同模型支持的参数不一样有些模型不支持某个参数会直接报错。开启这个选项后LiteLLM 会自动丢弃目标模型不支持的参数避免因为参数不兼容导致的请求失败。master_key是 LiteLLM 自己的访问密钥前端工具连接 LiteLLM 时要用这个。别和各个模型提供商的 key 搞混了。4.3 本地模型接入的注意事项热搜词里claude code 调用 lmstudio 的本地模型是个高频需求。用 LiteLLM 接本地模型的配置思路和接云端模型一样但有几个额外的坑上下文长度。本地模型的上下文窗口通常比云端模型小。如果你的项目文件很大Claude Code 一次性塞进去可能会超出本地模型的限制。解决办法是在 LiteLLM 配置里设置max_tokens上限或者在前端工具里控制发送的上下文量。响应速度。本地模型的推理速度取决于你的硬件。如果显卡不够强交互体验会比较差。我的建议是本地模型优先用于简单任务——比如代码补全、格式转换、单文件修改复杂任务还是交给云端模型。模型能力差异。本地开源模型在代码理解能力上和顶级云端模型还有差距。所以用本地模型时AGENTS.md 要写得更详细把更多隐含规则显式化弥补模型理解能力的不足。一个接本地模型的配置示例- model_name: local-coder litellm_params: model: openai/your-local-model api_base: http://localhost:1234/v1 api_key: not-needed max_tokens: 4096 timeout: 300timeout设大一点因为本地模型首次加载和长文本推理都可能比较慢。5. 把工具串起来一套可复现的协作工作流5.1 整体架构长什么样把前面讲的组件串起来完整的链路是这样的Claude Code / Codex (前端交互) ↓ LiteLLM (统一网关) ↓ ┌───────┼───────┐ 云端模型 本地模型 其他模型前端工具负责交互和项目上下文管理LiteLLM 负责协议转换和路由底层模型负责实际推理。AGENTS.md 则是贯穿整个链路的项目约定前端工具读取它来理解项目。这个架构的好处是每一层都可以独立替换。前端用腻了可以换模型想升级可以换而其他层不受影响。5.2 配置顺序与验证方法我建议的配置顺序是先 LiteLLM再前端工具最后 AGENTS.md。为什么这个顺序因为 LiteLLM 是基础层它不通上面都白搭。先把 LiteLLM 跑起来用 curl 验证一下能不能正常请求到模型curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: hello}] }能正常返回说明网关层通了。然后再配置前端工具指向 LiteLLM 的地址。最后写 AGENTS.md因为这时候你已经能正常和 AI 交互了可以边用边完善这个文件。5.3 日常使用中的分工策略工具都配好之后实际使用中怎么分工我的习惯是这样快速问答和小改动用 Codex启动快不占用太多上下文。复杂重构和代码库探索用 Claude Code它的项目感知能力更强。涉及敏感代码或需要离线的场景切到本地模型。日常大部分任务走云端模型保证质量。切换模型时如果前端工具支持配置多个 endpoint可以直接在工具内切换。如果不支持就改 LiteLLM 的配置然后重启。后者稍微麻烦点但胜在统一管理。6. 踩坑实录那些文档里不会写的问题6.1 代理配置导致的请求失败热搜词里出现了cc switch local proxy failed while handling codex endpoint /responses这类报错信息这让我想起一个非常典型的坑本地代理配置冲突。当你同时运行多个需要网络代理的工具时很容易出现端口冲突或者代理规则互相干扰的情况。表现就是某个工具突然连不上模型报一些看起来莫名其妙的错误。排查思路是这样的先确认 LiteLLM 本身能不能正常请求模型用 curl 直接测如果能说明问题在前端工具到 LiteLLM 这一段。然后检查前端工具的 endpoint 配置是否正确端口有没有被占用。最后检查系统层面的代理设置看是不是有全局代理规则拦截了本地请求。我的经验是本地服务之间的通信尽量在代理规则里排除掉。比如把localhost、127.0.0.1加入代理白名单避免本地请求被错误地转发出去。6.2 模型名称不匹配的报错热搜词里有个很具体的报错the gpt-5.6-sol model is not supported when using codex with a...。这类错误的本质是前端工具请求的模型名和 LiteLLM 配置里定义的 model_name 对不上。Codex 这类工具通常有自己的默认模型名如果你在 LiteLLM 里没有定义对应的 model_name请求就会失败。解决办法有两个一是在 LiteLLM 配置里加一个匹配的 model_name 别名二是修改前端工具的模型配置。我倾向于第一种因为改 LiteLLM 配置更集中不用去动每个前端工具。比如- model_name: gpt-5.6-sol litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY这样前端请求gpt-5.6-sol时实际走的是 gpt-4o。虽然名字对不上但能跑通。当然更好的做法是搞清楚前端工具为什么用这个模型名从根源上对齐。6.3 上下文丢失与文件读取失败用 Claude Code 这类项目感知工具时偶尔会遇到AI 好像没看到我的文件的情况。这通常不是工具坏了而是文件没有被正确纳入上下文。可能的原因包括文件在.gitignore里被排除了、文件太大超过了上下文限制、或者工具的索引还没更新。排查时先确认文件是否在项目根目录下且没有被忽略规则排除然后看文件大小是否合理。我的习惯是重要的配置文件、接口定义文件主动在对话里提一下比如参考 src/config/settings.py 里的配置结构。这样能确保 AI 确实读到了关键文件。6.4 权限与访问限制问题前面提到的your organization has disabled claude subscription access这类问题本质是账号权限层面的限制。遇到这种情况自己能做的排查很有限主要是确认账号类型、检查是否有可用的替代访问方式。如果确实受限那就考虑用 LiteLLM 接入其他模型来替代保证工作流不中断。这也是为什么我一直强调不要把工作流绑死在单一模型上。有了 LiteLLM 这层抽象某个模型用不了的时候换个模型继续干活影响可控。7. 关于这套工作流的一些个人体会用了这么久我最大的感受是AI 编程工具的价值很大程度上取决于你为它搭建的环境。同样的工具在配置完善的项目里和在裸奔的项目里表现差距是巨大的。AGENTS.md、LiteLLM 这些看起来是额外工作的东西实际上是在为 AI 提供它需要的上下文和灵活性。另一个体会是不要追求一步到位。我见过有人想一次性把 AGENTS.md 写到完美结果写了两天还没开始用。正确的做法是先写个最小版本用起来遇到问题再补充。这个文件是活的会随着你对项目的理解加深而不断完善。还有一点多模型策略是刚需不是锦上添花。不同模型在不同任务上的表现差异是真实存在的而且模型服务本身也会有波动。有一套能快速切换模型的机制能让你在遇到问题时从容很多。LiteLLM 在这方面帮了大忙。最后分享一个小技巧我会在 AGENTS.md 里专门留一个已知问题区块记录当前项目里 AI 容易搞错的地方。比如这个项目的日期处理统一用 UTC不要用本地时间、数据库连接池配置在 config/db.py 里不要新建配置文件。每次发现 AI 犯同样的错误就加一条进去。时间长了这个区块就成了项目的AI 避坑指南效果非常好。