OpenRouter + CLI + MCP：构建可脚本化 AI Agent 工具链实战

1. 从 treg 这个标题说起一个被低估的 CLI Agent 工具链入口第一次看到 treg 这个词很多人会以为是某个库的缩写或者拼写错误。但如果你最近在折腾 AI Agent 工具链尤其是围绕 OpenRouter、MCP、CLI 这一套生态就会意识到它大概率是一个把OpenRouter 密钥管理、Agent 调用、CLI 交互、MCP 协议对接揉在一起的轻量级命令行工具。我拿到这个标题的时候第一反应不是去查它到底是不是某个具体开源项目而是先拆它背后的关键词组合treg、OpenRouter、agent、CLI、MCP。这五个词放在一起指向的场景非常明确——在终端里跑一个能调用大模型、能挂载 MCP 工具、能通过 OpenRouter 统一路由的 Agent。为什么这个组合值得单独写一篇因为现在绝大多数人接触 Agent 的路径是先装一个桌面客户端再配 API Key再手动点来点去。但真正做开发、做自动化、做批量任务的人最终都会回到 CLI。CLI 的好处是它可以被脚本调用、可以被 CI 集成、可以被其他 Agent 当成子进程调度。而 OpenRouter 的价值在于它把多家模型的 API 统一成一个入口你不需要为每个模型单独维护一套密钥和计费逻辑。MCP 则是让 Agent 能真正动手的协议层没有 MCPAgent 只能聊天有了 MCPAgent 才能读文件、查数据库、调浏览器、操作设计稿。所以 treg 这个标题我把它理解成一个以 CLI 为交互形态、以 OpenRouter 为模型路由层、以 MCP 为工具扩展层、以 Agent 为执行主体的工具链实践。它解决的核心问题是如何用最少的配置在终端里获得一个可扩展、可脚本化、可切换模型的 Agent 运行环境。适合谁来参考三类人一是刚接触 Agent 开发、想找一个轻量入口的开发者二是已经在用 Codex CLI、Claude CLI 这类工具、想搞清楚底层路由和工具挂载逻辑的人三是需要把 Agent 能力嵌入自己工作流、但又不想被某个平台绑死的工程师。下面我会按照实际搭建和使用的顺序把这条链路拆开讲。不是官方文档的复述而是我自己踩过坑之后整理出来的可复现路径。2. 整体架构设计为什么是 OpenRouter CLI MCP 这个组合2.1 三层解耦模型层、交互层、工具层在动手之前先把架构想清楚比直接抄命令重要得多。我把这套东西分成三层模型层由 OpenRouter 承担。它对外暴露统一的 API 格式对内路由到不同厂商的模型。你只需要一个 OpenRouter API Key就能在 Claude、GPT、Gemini、Qwen 等模型之间切换。交互层由 CLI 承担。终端是你的主界面Agent 的输入输出、工具调用日志、错误信息都在这里呈现。工具层由 MCP 承担。MCP Server 提供具体能力比如文件系统访问、浏览器自动化、设计稿读取、数据库查询等。这三层解耦的好处是换模型不用改工具配置换工具不用改模型配置换交互方式不用动底层。很多人一开始把这三层揉在一起结果想换个模型就要重装一遍环境想加个工具就要改代码非常痛苦。2.2 为什么不用官方 SDK 直接调有人会问我直接用 OpenAI SDK 或者 Anthropic SDK 不就行了为什么要绕 OpenRouter原因有三个。第一密钥管理成本。如果你同时用三四家模型就要维护三四套密钥、三四套计费、三四套限流逻辑。OpenRouter 把这些统一了。第二模型切换成本。做 Agent 开发经常需要对比不同模型在同一个任务上的表现如果每次都要改代码里的 endpoint 和参数格式效率极低。第三可用性兜底。单一厂商偶尔会出现区域限流或服务波动OpenRouter 可以在多个上游之间做路由降低单点故障的影响。当然OpenRouter 也不是没有代价。它多了一层转发延迟会比直连略高某些模型的特殊参数可能不被完全支持计费上会有一个很小的加价。但对于开发和实验阶段来说这些代价完全可以接受。2.3 MCP 在这套架构里的位置MCP 全称是 Model Context Protocol你可以把它理解成 Agent 和外部工具之间的USB 接口。没有 MCP 之前每接一个工具就要写一套适配代码有了 MCP只要工具方提供了 MCP ServerAgent 就能按统一协议调用。在这套架构里MCP 的位置是工具层。CLI 负责把用户的自然语言指令传给 AgentAgent 通过 OpenRouter 调用模型做推理模型决定要调用哪个工具Agent 再通过 MCP 协议去调用对应的 MCP Server拿到结果后继续推理直到任务完成。这个链路听起来简单但实际配置时最容易出问题的就是 MCP 这一层。因为 MCP Server 的启动方式、参数传递、权限控制各不相同下面我会专门用一节来讲。3. 环境准备从零把 CLI Agent 跑起来3.1 OpenRouter 密钥获取与充值路径第一步是拿到 OpenRouter 的 API Key。入口就是 OpenRouter 官方站点注册后进入 Keys 页面创建一个新的 Key。这里有个细节创建 Key 的时候可以设置额度上限我强烈建议你给开发用的 Key 设一个较低的月度上限比如 5 到 10 美元。原因很简单Agent 跑起来之后很容易因为循环调用或者工具返回异常导致 token 消耗失控设上限是最后一道保险。关于充值OpenRouter 支持信用卡也有用户反馈可以通过支付宝完成充值。具体路径是进入账户的 Credits 页面选择充值金额然后按提示走支付流程。如果你在国内使用需要注意网络访问的稳定性这是使用任何海外 API 服务都要面对的现实问题建议提前确认好自己的网络环境。拿到 Key 之后不要直接写死在代码里。正确做法是放到环境变量export OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxxxxxx如果你用 macOS 或 Linux把这一行加到~/.zshrc或~/.bashrc里。Windows 用户可以在系统环境变量里配置或者用 PowerShell 的$env:OPENROUTER_API_KEY...临时设置。注意不要把 API Key 提交到 Git 仓库。我见过太多人因为把 Key 写进配置文件然后 push 到公开仓库导致额度被刷光。用.env文件的话记得把.env加进.gitignore。3.2 CLI 工具的安装与运行时检查CLI 工具这一块生态里比较常见的有 Codex CLI、Claude CLI以及一些基于 Node 或 Python 的第三方 Agent CLI。安装方式通常是 npm 全局安装或者 pip 安装。以 npm 为例npm install -g xxx/cli安装完之后第一件事不是急着跑而是检查运行时组件是否齐全。很多人会遇到这个报错unable to locate the codex cli binary or required runtime components. check这个报错的意思是 CLI 找不到它依赖的二进制文件或者运行时。常见原因有三个一是 Node 版本太低某些 CLI 要求 Node 18 以上二是全局安装路径没有加到 PATH 里三是依赖的某个原生模块没有编译成功。排查顺序建议这样先node -v确认版本再which xxx确认命令是否在 PATH 里最后看安装日志里有没有编译错误。如果是原生模块编译失败通常需要装 build tools比如 macOS 上的 Xcode Command Line Tools或者 Linux 上的build-essential。3.3 把 OpenRouter 接入 CLI 的配置方式不同 CLI 接入 OpenRouter 的方式略有差异但核心逻辑是一样的把 base URL 指向 OpenRouter 的 API 地址把 API Key 换成 OpenRouter 的 Key把模型名换成 OpenRouter 的模型标识。以常见的配置为例你需要在配置文件里写类似这样的内容{ provider: openrouter, baseUrl: https://openrouter.ai/api/v1, apiKey: ${OPENROUTER_API_KEY}, model: anthropic/claude-3.5-sonnet }这里的关键点是模型标识的写法。OpenRouter 用的是厂商/模型名的格式比如anthropic/claude-3.5-sonnet、openai/gpt-4o、google/gemini-pro。写错了模型名请求会直接返回 404 或者模型不存在。配置完之后跑一个最简单的测试xxx cli --prompt 你好请回复你的模型名称如果能看到正常回复说明模型层通了。如果报 401检查 Key如果报 404检查模型名如果报超时检查网络。4. MCP 工具层让 Agent 真正能干活4.1 MCP 是什么为什么它改变了 Agent 的能力边界MCP 协议的核心价值是把工具调用这件事标准化了。在 MCP 之前每个 Agent 框架都有自己的工具定义方式你为 A 框架写的工具换到 B 框架就要重写。MCP 出现之后工具方只需要提供一个 MCP Server任何支持 MCP 的 Agent 都能调用。举个具体例子。Playwright MCP 让 Agent 能操作浏览器Blender MCP 让 Agent 能操作 3D 软件蓝湖 MCP 让 Agent 能读取设计稿信息BurpSuite MCP 让 Agent 能参与安全测试流程。这些工具本身和 Agent 是解耦的Agent 只负责决定什么时候调用哪个工具具体怎么执行由 MCP Server 负责。这就带来一个很重要的变化Agent 的能力边界不再由 Agent 本身决定而是由你挂载了哪些 MCP Server 决定。你挂载了文件系统 MCPAgent 就能读写文件你挂载了数据库 MCPAgent 就能查数据你挂载了浏览器 MCPAgent 就能做网页自动化。4.2 MCP Server 的配置与启动方式MCP Server 的配置通常写在 CLI 的配置文件里格式大致如下{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/allowed/dir] }, playwright: { command: npx, args: [-y, playwright/mcp] } } }这里有几个实操要点。第一command和args的写法决定了 MCP Server 怎么启动。用npx的好处是不用提前全局安装但每次启动会检查包首次会慢一些。第二权限范围要收窄。比如 filesystem MCP 的最后一个参数是允许访问的目录千万不要写成根目录否则 Agent 理论上可以读写你整个磁盘。第三多个 MCP Server 可以同时挂载但要注意它们之间的工具名不能冲突。启动之后你可以通过 CLI 的 MCP 列表命令确认挂载状态xxx cli mcp list如果某个 Server 显示 failed通常是命令路径不对、依赖没装、或者参数格式错误。这时候单独在终端里跑一遍那个 command看具体报什么错比在 CLI 里猜要快得多。4.3 浏览器扩展里的 MCP 连接设置有一部分 MCP 能力是通过浏览器扩展暴露的比如某些网页操作类的工具。这类工具需要在浏览器扩展设置里启用「MCP 连接」然后配置本地端口或连接地址。这个环节最容易踩的坑是端口冲突和权限确认。端口冲突的排查很简单换个端口就行。权限确认则容易被忽略浏览器扩展通常需要你显式授权它访问当前标签页或者读取页面内容如果没授权MCP 调用会返回空结果或者权限错误。我的建议是第一次配置的时候先用一个最简单的页面做测试比如打开一个空白页让 Agent 通过 MCP 读取页面标题。如果能读到说明链路通了如果读不到再逐层排查扩展是否启用、端口是否监听、Agent 是否真的发起了调用。5. 实操全流程从安装到跑通第一个 Agent 任务5.1 完整安装步骤与验证清单把前面的内容串起来完整的安装流程是这样的确认 Node 版本在 18 以上Python 版本在 3.10 以上如果 CLI 依赖 Python。全局安装 CLI 工具确认命令在 PATH 里。配置 OpenRouter API Key 到环境变量。在 CLI 配置文件里设置 provider 为 openrouter填入 base URL 和模型名。配置至少一个 MCP Server建议从 filesystem 开始因为最容易验证。跑一个不涉及工具调用的纯对话测试确认模型层通。跑一个涉及工具调用的测试确认 MCP 层通。验证清单可以做成表格方便逐项打勾检查项验证命令预期结果Node 版本node -vv18 以上CLI 安装xxx --version显示版本号API Keyecho $OPENROUTER_API_KEY显示 Key 前缀模型连通xxx --prompt test正常回复MCP 挂载xxx mcp list显示已配置 Server工具调用让 Agent 读一个文件返回文件内容5.2 参数选择模型、温度、最大 token 怎么定Agent 场景下的参数选择和普通对话不一样。普通对话你追求的是回复质量Agent 场景你追求的是指令遵循的稳定性和工具调用的准确性。模型选择上我一般会准备两个一个能力强的做主推理比如 Claude 3.5 Sonnet 或 GPT-4o一个便宜快的做辅助任务比如摘要、分类、格式转换。OpenRouter 的好处就是你可以随时切换不用改代码。温度参数在 Agent 场景下建议调低0 到 0.3 之间。原因是温度越高模型越容易发挥而 Agent 需要的是严格按照工具定义去调用发挥反而容易出错。我实测下来温度设 0.1 的时候工具调用的参数格式错误率明显低于默认值。最大 token 要留足。Agent 的上下文里不仅有对话还有工具定义、工具返回结果、历史步骤很容易撑爆。如果 CLI 支持设置最大 token建议至少设到 8000 以上复杂任务设到 16000 或更高。5.3 一个真实任务的执行记录我拿一个实际任务来演示让 Agent 读取当前目录下的一个 Markdown 文件统计字数然后把结果写到一个新文件里。第一步Agent 通过 OpenRouter 调用模型模型判断需要调用 filesystem MCP 的读取工具。第二步MCP Server 返回文件内容。第三步模型对内容做字数统计。第四步模型调用 filesystem MCP 的写入工具把结果写到新文件。第五步模型返回任务完成。整个过程在终端里能看到每一步的工具调用日志。如果中间某一步失败日志会显示是模型推理出错还是 MCP 调用出错。这个区分非常重要因为排查方向完全不同。实操心得第一次跑带工具调用的任务时建议把日志级别调到 debug。虽然输出会很多但能清楚看到模型发了什么请求、MCP 返回了什么结果。等链路稳定了再调回正常级别。6. 常见问题与排查技巧实录6.1 模型层常见报错与处理报错信息可能原因处理方式401 UnauthorizedAPI Key 错误或未设置检查环境变量和 Key 有效性404 Model Not Found模型名写错核对 OpenRouter 模型标识429 Too Many Requests触发限流降低并发或换模型超时无响应网络问题检查网络连通性余额不足额度用完充值或换 Key这里重点说 429。Agent 场景下很容易触发限流因为一次任务可能包含多次模型调用。解决办法有两个一是降低单次任务的复杂度把大任务拆成小任务二是在 CLI 里配置重试逻辑遇到 429 时等待几秒再重试。6.2 MCP 层常见故障排查MCP 层的问题通常表现为Agent 说它要调用某个工具但调用失败或者调用返回空。排查思路是从下往上。先在终端里单独跑 MCP Server 的启动命令确认它能正常启动。然后用 MCP 的调试工具直接发一个请求确认它能正常返回。最后再通过 Agent 调用确认整条链路通。常见的具体问题包括MCP Server 依赖的某个命令不存在比如npx没装参数里的路径不存在或者没有权限多个 MCP Server 的工具名冲突导致 Agent 调用了错误的工具。6.3 Agent 执行中断与循环问题有一类报错很典型agent execution terminated due to error.这个报错信息很笼统实际原因可能是模型返回了不符合工具调用格式的内容也可能是 MCP 调用超时还可能是上下文超长被截断。我的排查顺序是先看 debug 日志里最后一次成功的步骤是什么再看失败的那一步模型发了什么、MCP 返回了什么。如果是格式问题通常是模型能力不够或者温度太高如果是超时检查 MCP Server 的响应时间如果是上下文超长减少历史步骤或者换更大上下文的模型。另一个常见问题是循环调用。Agent 反复调用同一个工具陷入死循环。这通常是因为工具返回的结果没有让模型判断出任务已完成。解决办法是在系统提示里明确告诉模型什么情况下应该停止或者设置最大步骤数限制。6.4 避坑清单我踩过的那些坑不要把 API Key 写进配置文件提交到仓库。不要给 filesystem MCP 开放根目录权限。不要在温度很高的情况下跑工具调用任务。不要忽略 CLI 的版本更新很多 MCP 兼容性问题在新版本里已经修了。不要在没确认网络稳定的情况下充值大额度。不要同时挂载太多 MCP Server工具太多反而会让模型选择困难。不要用生产环境的 Key 做实验单独建一个开发 Key。7. 进阶扩展这套链路还能怎么用7.1 把 Agent 嵌入自动化脚本CLI 形态最大的好处就是可以被脚本调用。你可以写一个 shell 脚本定时触发 Agent 执行某个任务比如每天早上读取指定目录的文件生成摘要写到固定位置。这种用法比桌面客户端灵活得多也更容易和现有的 CI/CD 流程结合。7.2 多模型对比与路由策略OpenRouter 支持在请求里指定模型也支持配置路由策略。你可以让 Agent 在简单任务上用便宜模型在复杂任务上用强模型。具体实现方式是在 CLI 配置里定义模型映射或者通过环境变量在运行时切换。我自己的做法是准备三套配置快速模式用便宜模型标准模式用中等模型深度模式用最强模型。根据任务类型手动切换比让 Agent 自己判断更可控。7.3 MCP 生态的持续扩展MCP 生态现在还在快速扩张新的 MCP Server 几乎每周都在出现。我的建议是不要一次性全装上而是按需挂载。先想清楚你当前的工作流里哪个环节最耗时然后去找对应的 MCP Server。比如你经常要处理设计稿就挂蓝湖 MCP经常要做网页测试就挂 Playwright MCP。最后分享一个我自己的习惯每次配置完一个新的 MCP Server我都会用一个最小任务验证它确认没问题之后再接入正式工作流。这样出问题的时候能快速定位是新加的 Server 导致的还是原有链路的问题。这个习惯帮我省了很多排查时间。