如果你跟我一样工作流里已经同时躺着 Codex CLI、Claude CLI再加上偶尔要用的 Qwen 命令行工具你会发现一个很尴尬的问题它们各自有各自的参数各自的 API Key各自的输出格式甚至连安装路径都各玩各的。每次想做个批量脚本都得先翻文档查命令最后写出来的 shell 脚本换个模型就崩。我做了一个叫 CLI-Anything 的小工具思路很简单把所有 AI 命令行工具收编到同一个入口下统一参数、统一配置、统一输出底层还是用各家官方 CLI 干活。这篇文章就聊聊这个项目为什么要做、核心设计怎么拆以及从安装到排错的完整实操记录。适合看这篇文章的人有两类一是日常重度使用终端、想在脚本里稳定调度不同 AI 模型的开发者二是刚接触 Codex CLI、Claude CLI被“装好了却调不通”“Key 填了但报错”这类问题折磨过的新手。我会把我在实际开发 CLI-Anything 过程中踩过的坑、想明白的取舍、以及那些文档里不会写的细节都摊开讲你可以直接照着抄。1. 为什么做 CLI-Anything被 AI CLI 工具“逼疯”后的设计思路1.1 我先讲几个真实场景过去半年我的终端工作流大概是这样的写代码时用 Codex CLI 做代码生成做文本重构时切到 Claude CLI临时想跑个中文场景时又得调 Qwen 的接口。这三个工具的常用命令风格差异很大。Codex CLI 倾向于交互式会话Claude CLI 有自己的一套claude -p prompt参数Qwen 那边的命令行工具又是另一种风格。我试过用 shell alias 去抹平差异但 alias 解决不了参数映射更解决不了 Key 管理的问题。更头疼的是脚本化。我想做一个自动化小任务每天早上让三个模型分别对同一段需求给方案然后对比结果。用原生命令写这个脚本等于要维护三套参数、三套输出解析规则。某次升级后其中一个 CLI 改了输出格式我的解析脚本立刻作废。这种脆弱感让我决定必须做一个中间层把复杂度收口。CLI-Anything 解决的核心问题就是让上层脚本只面对一套命令、一套返回结构底层各家 CLI 的变化都被适配器隔离掉。你可以把它理解成一个“统一插座”各个 AI 官方 CLI 是不同标准的插头适配器负责把它们转换成同一个接口。1.2 我的设计目标与取舍做这个工具之前我给自己定了几个原则。第一不重复造模型调用的轮子能调用官方 CLI 就调用官方 CLI这样模型的更新和官方功能比如长上下文、工具调用能自动跟上我不用维护大模型 API 协议细节。第二统一但不要过度收敛用户仍然可以透传某个 CLI 特有的参数CLI-Anything 只收编最常用的能力比如执行单次 prompt、查看版本、列出模型其余参数用--raw-args原样传给底层工具。第三配置必须外置Key 不写死在代码里支持 YAML 文件加环境变量两种方式方便不同机器迁移和 CI 环境注入。我也主动放弃了一些东西。比如不做“会话管理”不试图把 Codex 的交互式会话完整模拟出来因为交互式会话本身依赖各家终端 UI 特性强行统一会丢失体验。CLI-Anything 定位是“任务执行层”而不是“交互层”你想要沉浸式对话时应该直接用官方 CLI想做批量、自动化、多模型对比时再回到 CLI-Anything。这个边界想清楚后整个架构就简单多了。1.3 技术选型为什么是 Python技术栈上我选了 Python 3.11 Typer Pydantic进程调度用标准库subprocess。理由很务实AI CLI 生态的更新速度太快我需要一个开发效率高的语言去快速适配新工具Typer 能基于类型注解自动生成漂亮的命令行帮助对用户友好Pydantic 负责校验配置文件和结果结构让上层脚本拿到的一定是格式稳定的对象。有人会问为什么不用 Go 或 Rust编译成单个二进制确实更优雅但代价是每次各家 CLI 更新参数我都要重新编译发布。Python 脚本模式可以做到用户git pull就完成适配器更新对个人项目和中小团队来说这个优势更重要。实际跑下来Python 的启动延迟在 50ms 以内相对于模型推理动辄几秒的耗时完全可以忽略。2. CLI-Anything 核心实现细节与关键机制2.1 统一命令模型一组参数走天下CLI-Anything 设计了一套尽量精简的统一命令模型。最核心的子命令是run示例用法cli-anything run --provider codex --prompt 用Python写一个快速排序 --model gpt-5 cli-anything run --provider claude --prompt 给这段代码写注释 --model claude-sonnet-4-5 cli-anything run --provider qwen --prompt 解释一下什么是DDD --model qwen-max从使用者角度看只需要关心四个统一参数--provider指定适配器--prompt输入文本--model选择模型--output-format指定返回的是纯文本还是 JSON。其他参数像温度、最大 token、system prompt我做了常见映射虽然名字统一但内部会翻译成各家 CLI 实际的参数。这个设计背后的一个关键决策是参数映射表不能放在主程序里而要放在适配器内部。原因很简单不同 CLI 对“温度”这个参数的写法不一样Codex 可能叫--temperatureClaude 可能有自己的格式Qwen 可能完全用-t简写。如果主程序统一管理这些映射那每新增一个 provider 都要改主程序违背了开闭原则。所以我把映射逻辑全部下沉到适配器主程序只调用一个标准接口adapter.build_command(request)剩下的细节由适配器自己搞定。还有一个细节值得提Prompt 的传递安全。直接拼接--prompt参数到命令行容易遇到特殊字符、引号、换行符导致命令注入或参数解析错乱。我的处理方式是使用subprocess.run的列表模式list form不经过 shell并且把 prompt 通过标准输入stdin传给那些支持--stdin的 CLI对于必须用参数传入的 CLI会做一层转义并限制长度防止命令行溢出。2.2 适配器层设计每个 CLI 都是可插拔的适配器是 CLI-Anything 最重要的抽象。我定义了一个很薄的基类约等于一个协议class BaseAdapter: name binary_hint def detect(self) - bool: 检查对应CLI是否已安装 def build_command(self, request: Request) - list[str]: 把统一请求翻译成目标CLI命令 def parse_output(self, stdout: str, stderr: str) - Result: 把CLI输出转成统一结构以 Codex 适配器为例我调用的是官方 Codex CLI 的批处理模式核心逻辑大致是class CodexAdapter(BaseAdapter): name codex binary_hint codex def build_command(self, request: Request): cmd [codex, exec] if request.model: cmd [--model, request.model] if request.temperature: cmd [--temperature, str(request.temperature)] return cmd def parse_output(self, stdout, stderr): # 处理Codex输出的思路标记块提取最终回答 return extract_text(stdout)Claude 适配器则优先调用claude -p的非交互模式这个模式天然适合脚本调用。它同样会输出一些诊断信息到 stderr因此解析时我会过滤掉\r、控制字符并尝试从stdout最后的部分提取有效回答。Qwen 适配器最直接如果系统里有官方命令行就直接调用没有的话会退化为调用 DashScope 兼容接口的 HTTP 请求。这个“退化”逻辑其实是适配器里很重要的一环它保证了即使官方 CLI 没装CLI-Anything 依然可以完成模型调用。这种双通道设计用到了生活里常见的“适配器”类比你买了个转接头一端是 USB-C另一端可能是 HDMI可能是 VGA。转接头不需要知道显示器内部怎么工作只需要完成物理规格的转换。CLI-Anything 的适配器也一样它不关心模型内部逻辑只负责把统一请求“翻译”成每个 CLI 能听懂的方言。2.3 配置与密钥管理Key 不落盘权限最小化密钥管理是这类工具最容易翻车的地方。很多人的习惯是把 API Key 写在命令里比如codex --api-key sk-xxx但这样做不仅会留在 shell history 里还容易在截图、录屏时泄露。CLI-Anything 的配置默认放在~/.cli-anything/config.yaml结构非常直白providers: codex: enabled: true binary: codex env: OPENAI_API_KEY: {env:CODEX_API_KEY} claude: enabled: true binary: claude env: ANTHROPIC_API_KEY: {env:CLAUDE_API_KEY} qwen: enabled: true binary: null env: DASHSCOPE_API_KEY: {env:QWEN_API_KEY}这里有个重要设计配置文件里不直接存 Key而是用{env:VAR_NAME}这种占位符引用环境变量。程序启动时会把占位符替换成环境变量的实际值然后设置到子进程的环境中。这样做的好处有三层第一配置文件可以安全地提交到 Git 仓库不会泄露密钥第二在 CI 里只要在任务配置中注入环境变量不需要修改任何代码第三不同 provider 的 Key 互相隔离不存在“一个 Key 到处用”的混乱。在实际开发中我还加了一道“防呆检查”如果环境变量未设置CLI-Anything 不会直接报错退出而是提示具体是哪个 provider 缺哪个变量并且建议用户使用cli-anything doctor命令做一次自检。这个命令会检查每个 provider 的 binary 是否存在、环境变量是否有值、配置文件语法是否正确把排查时间从半小时压缩到几秒钟。2.4 流式输出与并行执行把多个模型当成一支小队脚本化场景里有两个高频需求让用户实时看到输出以及同时调用多个模型做横向对比。第一个需求要求我们不能等子进程完全结束才输出而要用subprocess.Popen逐行读取stdout用print(..., flushTrue)实时打出来。第二个需求更复杂因为 Python 默认的subprocess.run是阻塞的串行调用三个模型耗时是三倍。CLI-Anything 用concurrent.futures.ThreadPoolExecutor做并行调用每个 provider 跑在线程里主程序收集结果后统一返回。并行听起来简单但有个坑多个子进程同时往终端写内容会互相穿插输出就像几队人同时喊口号谁也听不清。我的解决办法是给每个并行任务加一个“缓冲小桶”先用队列收集各自输出等任务完成后再按 provider 顺序打印如果要看实时流式输出就使用--stream参数切换到“谁先出结果先打谁”的模式但会在每条输出前打上[provider]前缀避免混淆。这个能力在实际使用中帮了大忙。比如我写一个对比脚本让 Codex、Claude、Qwen 分别写同一个函数最后自动生成一张对比表。没有 CLI-Anything 之前这个脚本至少要写两百行现在核心逻辑不到二十行而且因为输出结构统一后续解析、入库、生成 Markdown 都很轻松。3. 实操从安装到跑通一个真实任务3.1 安装 CLI-Anything 并确认环境如果你只是用推荐直接通过 pip 安装pip install cli-anything如果你想改代码或者加自己的适配器就克隆仓库后以可编辑模式安装git clone https://github.com/yourname/cli-anything.git cd cli-anything pip install -e .装完先跑一下版本号和自检确认框架本身没问题cli-anything --version cli-anything doctordoctor命令会输出一张表格列出 codex、claude、qwen 三个核心适配器的检测状态。有一个很容易踩的坑如果你的环境里有pyenv或condapip装出来的cli-anything命令可能不在当前 shell 的 PATH 里。遇到command not found不要急着重装先执行python -m cli_anything --version如果能运行说明只是 bin 目录没进 PATH加一下路径就行。3.2 初始化配置并接入 Codex CLI安装完成后执行cli-anything init它会生成默认的config.yaml同时打印一份模板让你填写环境变量名。接下来以 Codex 为例先确认 Codex CLI 本身能跑which codex codex --version确认没问题后在 shell 配置文件里设置 Keyexport CODEX_API_KEYsk-your-key然后在 CLI-Anything 里验证一下能不能正确读取cli-anything provider status codex如果你看到binary: found和env: ok说明适配器已经准备好。接下来直接跑一个最简单的任务cli-anything run --provider codex --prompt 用三句话解释什么是幂等性正常情况下你会看到 Codex 的流式输出。我第一次跑的时候犯了个错忘了设置CODEX_API_KEY结果 doctor 提示缺变量但我以为是 CLI-Anything 没装好折腾了半天。后来把cli-anything doctor纳入每次换机器时的固定流程这个错再没犯过。3.3 多模型对比任务一次调用三个模型设置完 Claude 和 Qwen 的 Key 后就可以体验 CLI-Anything 最有价值的功能一句话同时问三个模型。cli-anything run \ --provider codex,claude,qwen \ --prompt 用Python写一个读取大文件的生成器 \ --output-format json--provider参数支持逗号分隔的列表内部会走并行执行通道。--output-format json会让 CLI-Anything 输出一个 JSON 数组每个元素包含 provider、model、raw_output、parsed_output 和耗时。我自己写脚本时最常用这个格式直接拿jq或 Python 的json模块处理非常干净。对比任务里有个小技巧你可以在请求中加--system 你是资深Python工程师回答需包含代码和复杂度分析CLI-Anything 会把这段 system prompt 翻译给所有支持该参数的 provider实现“同一个任务、同一个限定条件”的效果。如果某个 provider 不支持 system prompt适配器会自动忽略并打一行警告不会中断整个任务。3.4 在 Mac 上“用 Qwen Key 驱动 Claude CLI”的正确理解有不少人看到“mac claude cli 用 qwen key”这种说法以为 Claude CLI 可以直接配通义千问的 Key。这里我必须说清楚Anthropic 官方 CLI 默认只认 Anthropic 体系的 Key你直接把 Qwen 的 Key 填到ANTHROPIC_API_KEY里大概率会得到鉴权失败。CLI-Anything 不会去 hack 官方 CLI 的鉴权逻辑那既不安全也不可持续。正确的用法是把 Qwen 的模型能力挂到 CLI-Anything 的统一入口下。这样你的脚本写的是--provider qwen真正调用的是 DashScope 兼容接口Qwen 的 Key 只存在于 Qwen 适配器的环境变量里完全不需要碰 Claude CLI。如果你真的很喜欢 Claude CLI 的交互界面想在里面用 Qwen 模型需要看 Qwen 官方是否提供 Anthropic 兼容端点而不是靠改环境变量变量名来碰运气。我在 Mac 上实测过的稳定组合是CLI-Anything QwenAdapter DASHSCOPE_API_KEY用起来非常顺。对普通用户来说不要把时间和安全性浪费在“让一个官方工具强行认另一个厂商的 Key”上正确做法是让统一入口去兼容不同 Key而不是让 Key 互相冒用。4. 常见问题与排查技巧实录4.1 “unable to locate the codex cli binary or required runtime components” 的完整排查这条报错是 Codex 适配器最常遇到的问题。我把它拆成几个层面来解决。第一层确认 binary 本身是否存在which codex ls -l $(which codex)如果 which 没输出说明 Codex CLI 没安装或安装到了不常见的位置。常见原因包括用npm install -g openai/codex时 npm 的全局 bin 目录不在 PATH 里用某些版本管理器安装后可执行文件在版本目录下但软链没建好。解决办法是把对应 bin 目录添加到 PATH或直接给config.yaml里的binary字段填绝对路径。第二层确认 runtime components。Codex 某些版本依赖 Node.js 运行时如果你本机的 Node 版本过低或没有装 npm 依赖仅靠 binary 存在并不能保证能跑。你可以手动执行codex --version如果报错信息里提到了runtime components说明可能是安装目录内的依赖缺失。最直接的办法是重装一遍 Codex CLI再检查npm list -g --depth0看包是否完整。第三层还有一个我踩过的坑某些 shell 环境下PATH 在启动 CLI-Anything 时没有被完整加载。特别是在 mac 上通过 GUI 启动的终端比如 iTerm 的某个配置可能读不到~/.zshrc里的 PATH 设置。CLI-Anything 的doctor命令会打印当前进程实际解析到的 PATH如果你发现它和你终端里的 PATH 不一样就要在启动脚本里显式 source 对应配置文件。4.2 Key 相关和模型参数的典型问题速查我把这段时间收集到的常见问题整理成了表格方便快速定位。症状常见原因处理方式提示缺环境变量变量名和config.yaml不一致或变量未 export执行cli-anything doctor按提示检查模型名不存在各家模型的型号列表不同名称拼写错误在config.yaml中删除model触发默认模型请求超时模型本身推理慢或并发数太高增加--timeout减少--provider并发数返回结果为空官方 CLI 把回答输出到了 stderr 或需要交互确认用--raw-args -- -v查看原始输出定位原因Windows 下路径找不到Python 与 npm 的 bin 目录路径不一致在适配器配置里指定绝对路径或用wsl运行还有一个容易忽略的点Claude CLI 经常需要先登录或做一次授权如果在无交互的 CI 环境中运行授权会失败。CLI-Anything 遇到这种情况会捕获到 stderr 中的关键字段并给出一段提示“Claude CLI 可能处于未登录状态请先在终端运行claude完成一次交互登录”。这个提示是我加的最有用的错误处理之一因为它把用户从一个没头没尾的exit code 1里解放了出来。4.3 输出乱码、混入诊断信息与流式刷新问题官方 CLI 的输出格式各不相同解析时经常会遇到三个问题。第一个是 ANSI 颜色码有些 CLI 检测到非 TTY 环境会自带颜色另一些即使重定向也强行输出颜色导致 JSON 解析失败。我的方案是在适配器里统一去掉 ANSI 转义序列只保留纯文本。第二个问题是诊断信息进入 stdout比如某些 CLI 会在正式回答前打印一段统计信息。处理这个需要结合具体工具的特征做截断或正则提取。比如 Codex 的批处理输出有时会包含被---包裹的元数据适配器会通过“取最后一个代码块之后的文本”这种简单策略来提取回答。第三个问题是流式刷新。很多模型是边生成边输出的如果你用subprocess.run(capture_outputTrue)等全部完成用户会盯着屏幕干等。CLI-Anything 在--stream模式下的实现是启动一个线程持续读取子进程 stdout每读一行就写入主程序的 stdout 并 flush。注意这里不能用默认的缓冲否则一行可能攒很久才显示。我一开始就吃过这个亏加了flushTrue之后体验立刻正常了像极了博客里常说的“就差这一行”。4.4 几条独门经验调试、扩展和安全最后分享三个我在开发中沉淀下来的经验。第一一定要给适配器加一个--dry-run选项只打印将要执行的完整命令不真正执行。简化版用法cli-anything run --provider codex --prompt hi --dry-run这条命令会输出codex exec --model ...之类的完整命令对调试参数映射有奇效。第二如果你要扩展自己的 CLI优先复制一个现有适配器再改不要从零写。因为二进制探测、输出解析、环境变量注入这些逻辑都是重复的基于现有结构改只需要关注build_command和parse_output快很多。第三把cli-anything doctor固化在初始化和定期维护的流程里。工具越多环境变量和 binary 版本越容易漂移定期自检能提前发现一半以上的诡异问题。再说一个安全习惯CLI-Anything 默认会拒绝把 API Key 写到命令行参数中传给子进程因为命令行参数对其他进程可见ps aux能看到。虽然官方 CLI 大概率不会主动打印 Key但多一层安全边界总是好事。我在设计规范里明确所有 Key 只用环境变量传递配置文件的{env:...}是唯一推荐写法。这个决策在面对审计和团队协作时尤其受益。这个项目目前已经成了我日常脚本里的常驻组件。后续我还想加一个简单的插件市场机制让大家把各自适配器打包上传用cli-anything plugin install一条命令即可安装。如果你也被五花八门的 AI 命令行工具折磨过不妨先用 CLI-Anything 把入口收拢至少整个工作流会清爽很多。最后再提一条个人体会工具的价值不在于功能多而在于把你的输入和输出稳定下来之后不管是换模型还是加模型上层的脚本都不用动这才是 CLI-Anything 最吸引我的地方。