CLI Agent 工具链实战：OpenRouter + MCP 协议 + 本地执行入口

1. 从 "treg" 这个标题说起：一个被低估的 CLI Agent 工具链入口

第一次看到 "treg" 这个词，大概率会一脸懵——它不像codex、claude那样自带品牌辨识度，也不像mcp那样有明确的协议含义。但如果你最近在折腾 AI Agent 的 CLI 工具链，尤其是围绕 OpenRouter、MCP 协议、agent 执行框架这一套生态，就会发现 "treg" 更像是某个具体项目、脚本或者内部工具链的代号，它的价值不在于名字本身，而在于它背后串起来的那一整条链路：OpenRouter 提供模型路由能力，MCP 提供工具调用协议，CLI 提供本地执行入口，Agent 负责编排决策。

我接触这套东西的起点其实很朴素：手头有一堆零散的 CLI 工具，每个都要单独配 key、单独记命令、单独处理报错，切换模型要改配置文件，接一个新工具要重写一遍胶水代码。后来发现 OpenRouter 这类聚合入口能把模型调用统一成一套 API，MCP 能把工具能力标准化成 server，剩下的问题就是——怎么用一个统一的 CLI 入口把它们串起来，让 agent 真正跑起来而不是停在 demo 阶段。treg 这个标题对应的，正是这个"最后一公里"的问题。

这篇文章适合三类人看：第一类是想从零搭一套本地 agent 工作流、但被各种 CLI 和协议绕晕的开发者；第二类是用过 codex cli、claude cli 这类工具，想搞清楚底层 agent 执行逻辑和 MCP 协议怎么配合的人；第三类是做 agent 开发、需要一套可复现的 CLI + OpenRouter + MCP 组合方案的工程师。我会把整条链路的选型逻辑、配置细节、踩坑记录都摊开讲，代码和参数尽量给到能直接抄的程度。

需要先说明一点：treg 本身在公开资料里没有特别权威的统一定义，不同团队内部可能指代不同的东西。所以下文我把它当作一个典型的 CLI Agent 工具链项目代号来处理，重点讲这类项目在 OpenRouter + MCP + Agent 这套组合下通用的设计思路和实操方法。这个前提很重要，避免你拿着某个具体产品的预期来对号入座。

2. 整体架构设计：为什么是 OpenRouter + MCP + CLI 这个组合

2.1 三个组件各自的定位与不可替代性

先把三个核心组件拆开看，理解它们各自解决什么问题，才能明白为什么这套组合能成立。

OpenRouter的核心价值是模型路由与统一计费。你不需要为每个模型厂商单独申请 key、单独处理不同的 API 格式、单独充值。一个 OpenRouter API key 就能调用几十个不同厂商的模型，接口格式统一，计费统一，还能按需切换。对于 agent 场景来说这点尤其关键——agent 执行过程中可能需要不同能力的模型，规划用强模型、执行用快模型、总结用便宜模型，如果每个都单独接，维护成本会爆炸。

MCP（Model Context Protocol）解决的是工具能力的标准化接入。在没有 MCP 之前，你给 agent 接一个工具（比如读文件、查数据库、调浏览器），要写一堆适配代码，每个工具一套逻辑。MCP 把这些能力抽象成 server，agent 作为 client 通过标准协议调用，工具的实现和 agent 的逻辑彻底解耦。playwright mcp、blender mcp、蓝湖 mcp 这些就是不同领域工具按 MCP 协议封装后的产物。

CLI则是本地执行的入口和交互层。为什么不用 Web UI 或者纯 API 调用？因为 agent 执行过程中大量操作是本地文件、本地命令、本地环境，CLI 天然贴近这些场景，而且易于脚本化、易于集成到现有工作流。codex cli、claude cli、deveco cli 这些工具的火爆，本质上都是因为开发者需要一个"在终端里就能指挥 agent 干活"的入口。

三者组合起来，形成的是一个模型能力可插拔、工具能力可插拔、执行入口轻量化的架构。这个架构最大的好处是每一层都能独立替换：模型层换 OpenRouter 上的其他模型，工具层加新的 MCP server，入口层甚至可以换成别的 CLI 或者 IDE 插件，互不影响。

2.2 为什么不用单一厂商全家桶

很多人会问：直接用某一家厂商的 CLI + 官方模型 + 官方工具生态不就行了，为什么要搞这么复杂？

我实测下来的结论是：单一厂商全家桶在 demo 阶段很爽，在生产阶段会卡死你。原因有三个。

第一是模型锁定。官方 CLI 通常只对接自家模型，你想换个更便宜或者更适合某个任务的模型，要么等官方支持，要么自己改源码。而 agent 任务对模型的要求差异极大，代码生成、长文本理解、工具调用准确性，不同模型表现完全不同，锁死一个模型等于放弃了优化空间。

第二是工具生态锁定。官方工具生态通常只覆盖自家定义的场景，你想接一个内部的数据库、一个自研的 API、一个特定领域的工具，要么等官方出插件，要么自己写适配。MCP 协议的价值就在于它把这件事标准化了，任何工具只要实现 MCP server，就能被任何支持 MCP 的 agent 调用。

第三是成本不可控。官方 CLI 通常绑定官方计费，你没法做精细的成本优化。OpenRouter 这类聚合入口的好处是你可以按任务类型选模型，简单任务用便宜模型，复杂任务用强模型，整体成本能压下来一大截。

提示：如果你的 agent 任务非常单一、对成本不敏感、也不需要接自定义工具，那单一厂商全家桶确实更省事。这套组合方案的价值在复杂场景下才体现得出来。

2.3 treg 这类项目的典型目录结构

基于常见实践，一个典型的 CLI Agent 工具链项目（也就是 treg 这类代号对应的东西）目录结构大概是这样：

treg/ ├── config/ │ ├── openrouter.yaml # 模型路由配置 │ ├── mcp_servers.json # MCP server 注册表 │ └── agent.yaml # agent 行为配置 ├── src/ │ ├── cli/ # CLI 入口与命令解析 │ ├── agent/ # agent 核心循环 │ ├── mcp_client/ # MCP 协议客户端 │ └── router/ # OpenRouter 调用封装 ├── tools/ # 本地工具与脚本 ├── logs/ # 执行日志 └── README.md

这个结构的关键在于配置与代码分离。模型配置、MCP server 注册、agent 行为参数都放在 config 目录，改配置不用动代码。这是这类项目能长期维护的前提，我见过太多把 key 和模型名硬编码在代码里的项目，换一次模型要改十几个文件。

3. 核心细节解析：OpenRouter 接入与 MCP 协议实操要点

3.1 OpenRouter API Key 获取与充值路径

OpenRouter 的接入第一步是拿 key。官方入口进去注册账号，在 keys 页面生成 API key，这个流程不复杂。真正容易卡住的是充值环节——OpenRouter 支持信用卡，但对国内用户来说，支付宝这条路是很多人关心的。实测下来，OpenRouter 的支付方式会随地区和时间变化，最稳妥的做法是先在账户的 billing 页面看当前支持的支付方式，不要盲目按网上的老教程操作。

关于"openrouter 密钥大全"这类搜索词，我必须提醒一句：任何声称提供"密钥大全"的来源都不可信。API key 是绑定账户和计费的，用别人的 key 要么随时失效，要么涉及账号安全问题。正确做法是自己注册、自己充值、自己管理 key。

key 的管理有几个实操要点：

• 不要硬编码。用环境变量或者配置文件，且配置文件加入.gitignore。
• 按用途分 key。如果 OpenRouter 支持多 key，给不同项目、不同环境分不同的 key，方便追踪成本和出问题时快速定位。
• 设置额度上限。在 OpenRouter 后台给 key 设置消费上限，避免 agent 跑飞了烧钱。

配置到项目里的形式大概是这样：

# config/openrouter.yaml provider: openrouter api_key: ${OPENROUTER_API_KEY} # 从环境变量读取 base_url: https://openrouter.ai/api/v1 models: planner: name: anthropic/claude-3.5-sonnet max_tokens: 4096 executor: name: openai/gpt-4o-mini max_tokens: 2048 summarizer: name: google/gemini-flash-1.5 max_tokens: 1024

这里按角色分模型是核心设计。planner 用强模型保证规划质量，executor 用快模型保证执行速度，summarizer 用便宜模型控制成本。这个分层策略是我踩了很多坑之后总结出来的——一开始所有环节都用同一个强模型，成本高得离谱，而且执行环节用强模型并没有明显收益。

3.2 MCP 协议到底是什么，为什么 agent 需要它

MCP 是什么？用一句话说：它是让 agent 和工具之间用统一语言对话的协议。类比一下，就像 USB 接口——以前每个设备一个接口，现在统一成 USB，任何设备插上就能用。MCP 就是 agent 工具生态的 USB。

没有 MCP 的时候，agent 要调用一个工具，流程是这样的：agent 输出一段特定格式的文本，你的代码解析这段文本，识别出要调哪个工具、传什么参数，然后执行，再把结果拼回 prompt。每个工具都要写一遍这套逻辑，工具一多就乱套。

有了 MCP 之后，工具被封装成 MCP server，agent 作为 MCP client 通过标准协议（通常是 stdio 或 HTTP）和 server 通信。server 自己声明有哪些工具、每个工具需要什么参数，agent 动态发现这些能力。加一个新工具，只需要注册一个新的 MCP server，agent 代码一行不用改。

MCP server 的注册配置大概长这样：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"] }, "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }, "custom-db": { "command": "python", "args": ["-m", "my_mcp_servers.db_server"], "env": { "DB_CONNECTION": "${DB_CONNECTION}" } } } }

这个配置里，每个 server 声明了启动命令和参数。agent 启动时会拉起这些 server，通过 stdio 和它们通信。playwright mcp 让 agent 能操作浏览器，filesystem server 让 agent 能读写文件，custom-db 是你自己封装的数据库工具。

3.3 CLI 入口的设计：命令解析与 agent 循环

CLI 这一层看起来简单，其实是最影响使用体验的部分。一个好的 CLI agent 入口要处理几件事：命令解析、会话管理、agent 循环驱动、输出渲染。

命令解析用现成的库就行，Python 用click或typer，Node 用commander或yargs。关键是命令设计要符合直觉，比如：

treg run "帮我重构 src/utils 下的工具函数" # 执行一个任务 treg chat # 进入交互模式 treg mcp list # 列出已注册的 MCP server treg mcp add <name> <command> # 添加 MCP server treg config show # 查看当前配置

agent 循环是核心。一个典型的 agent 循环逻辑是：接收用户输入 → 调用模型 → 模型返回工具调用请求 → 执行工具 → 把结果喂回模型 → 重复直到模型返回最终答案。这个循环里最容易出问题的是终止条件和错误处理。

def agent_loop(task, max_iterations=20): messages = [{"role": "user", "content": task}] for i in range(max_iterations): response = call_model(messages) if response.has_tool_calls(): for call in response.tool_calls: result = execute_mcp_tool(call) messages.append({"role": "tool", "content": result}) else: return response.content raise AgentMaxIterationsError("agent 超过最大迭代次数")

max_iterations这个参数非常关键。没有它，agent 可能陷入死循环，一直调用工具但永远不收敛，烧钱又浪费时间。我一般设 15 到 20，复杂任务可以放宽到 30，但一定要有上限。

4. 实操过程：从零搭一套可跑的 CLI Agent 工作流

4.1 环境准备与依赖安装

先把基础环境搭起来。假设你用 Python 做 CLI，需要的东西不多：

# 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate # 安装核心依赖 pip install openai click pyyaml mcp # 如果要用 playwright mcp，还需要 pip install playwright playwright install chromium

这里openai库是用来调 OpenRouter 的，因为 OpenRouter 兼容 OpenAI 的 API 格式，直接用 openai 的 SDK 改 base_url 就行。mcp是官方协议库，click做 CLI，pyyaml读配置。

环境变量配置：

export OPENROUTER_API_KEY="你的key" export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"

注意：环境变量在 Windows 和 macOS/Linux 下的设置方式不同，Windows 用set或$env:，macOS/Linux 用export。如果要在多个终端会话里持久化，写进 shell 的配置文件（.bashrc、.zshrc）或者用.env文件配合python-dotenv。

4.2 OpenRouter 调用封装与模型路由实现

封装 OpenRouter 调用的核心是把模型选择逻辑抽出来。不要在每个调用点写死模型名，而是通过角色名去配置里查。

import os from openai import OpenAI import yaml class ModelRouter: def __init__(self, config_path="config/openrouter.yaml"): with open(config_path) as f: self.config = yaml.safe_load(f) self.client = OpenAI( api_key=os.environ["OPENROUTER_API_KEY"], base_url=self.config["base_url"] ) def call(self, role, messages, tools=None): model_cfg = self.config["models"][role] kwargs = { "model": model_cfg["name"], "messages": messages, "max_tokens": model_cfg["max_tokens"], } if tools: kwargs["tools"] = tools response = self.client.chat.completions.create(**kwargs) return response.choices[0].message

这个封装的好处是，切换模型只改 yaml，代码不动。而且可以很方便地加日志、加重试、加成本统计。

关于模型选择，我实测下来几个经验：工具调用准确性比模型整体能力更重要。有些模型文本生成很强，但工具调用格式经常出错，这种模型在 agent 场景下反而不好用。选模型的时候优先看它在 function calling 上的表现，而不是看它在通用 benchmark 上的分数。

4.3 MCP Server 接入与工具调用链路打通

MCP server 的接入分两步：注册和调用。注册就是前面说的配置文件，调用需要实现 MCP client 逻辑。

from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class MCPManager: def __init__(self, config_path="config/mcp_servers.json"): with open(config_path) as f: self.servers = json.load(f)["mcpServers"] self.sessions = {} async def start_server(self, name): cfg = self.servers[name] params = StdioServerParameters( command=cfg["command"], args=cfg["args"], env=cfg.get("env") ) read, write = await stdio_client(params).__aenter__() session = ClientSession(read, write) await session.initialize() self.sessions[name] = session async def list_tools(self): all_tools = [] for name, session in self.sessions.items(): tools = await session.list_tools() for tool in tools.tools: all_tools.append({ "name": f"{name}__{tool.name}", "description": tool.description, "input_schema": tool.inputSchema }) return all_tools async def call_tool(self, full_name, arguments): server_name, tool_name = full_name.split("__", 1) session = self.sessions[server_name] result = await session.call_tool(tool_name, arguments) return result.content

这里有个细节：工具名要加 server 前缀。因为不同 server 可能有同名工具，加前缀避免冲突。调用的时候再拆开，路由到对应的 server。

工具列表拿到之后，要转换成模型能理解的格式（OpenAI 的 function calling 格式），喂给模型。模型返回工具调用请求后，再通过 MCPManager 执行，把结果拼回消息列表。

4.4 完整 agent 执行流程串起来

把上面几块拼起来，一个完整的 agent 执行流程是这样的：

async def run_agent(task): router = ModelRouter() mcp = MCPManager() # 启动所有 MCP server for name in mcp.servers: await mcp.start_server(name) # 获取工具列表并转换格式 tools = await mcp.list_tools() openai_tools = convert_to_openai_format(tools) messages = [{"role": "user", "content": task}] for i in range(20): response = router.call("planner", messages, tools=openai_tools) if not response.tool_calls: return response.content messages.append(response) for call in response.tool_calls: result = await mcp.call_tool( call.function.name, json.loads(call.function.arguments) ) messages.append({ "role": "tool", "tool_call_id": call.id, "content": str(result) }) return "任务未在限定步数内完成"

这个流程跑通之后，你就有了一个能接收自然语言任务、自动调用工具、返回结果的 CLI agent。实测下来，filesystem + playwright 这两个 MCP server 组合已经能覆盖大部分日常任务，比如"帮我看看这个网页的结构然后生成一份报告"、"把这个目录下的日志文件分析一下找出错误"。

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

5.1 CLI 安装与运行时问题排查

问题一：unable to locate the codex cli binary or required runtime components

这个报错在 codex cli 安装过程中很常见。原因通常是二进制没装到 PATH 里，或者运行时依赖缺失。排查步骤：

1. 确认二进制实际位置：which codex或where codex
2. 检查 PATH：echo $PATH，看二进制所在目录在不在里面
3. 检查运行时：如果是 Node 写的，确认 Node 版本符合要求；如果是 Python 写的，确认 Python 环境和依赖装全了
4. 重新安装：用官方推荐的安装方式重装一遍，不要用来源不明的安装包

问题二：agent execution terminated due to error

agent 执行中途报错终止，这个报错信息太笼统，需要看日志定位。常见原因和排查方向：

5.2 模型调用与密钥管理避坑

坑一：key 泄露。我见过有人把 key 直接写在代码里然后推到公开仓库，几分钟内就被扫到并盗刷。正确做法是用环境变量，且.env文件加入.gitignore。如果不小心泄露了，第一时间去 OpenRouter 后台吊销旧 key 生成新的。

坑二：模型名写错。OpenRouter 的模型名格式是厂商/模型名，比如anthropic/claude-3.5-sonnet。写错的话会报模型不存在。建议在 OpenRouter 的模型列表页面复制准确的模型名，不要手打。

坑三：额度耗尽没预警。agent 跑起来之后 token 消耗很快，尤其是长任务。建议在 OpenRouter 后台设置额度预警，同时在代码里加 token 统计，每次调用后累加，接近上限时主动停止。

5.3 MCP 工具调用失败的典型场景

场景一：server 启动失败。MCP server 启动失败通常是因为命令不对或者依赖没装。排查方法是手动执行配置里的 command 和 args，看能不能正常启动。比如npx -y @playwright/mcp手动跑一下，如果报错就能看到具体原因。

场景二：工具参数不匹配。模型生成的参数和工具 schema 对不上，比如该传字符串传了数字，该传数组传了对象。这种情况要么在 prompt 里加强参数说明，要么在调用前做参数校验和修正。

场景三：工具返回结果太大。有些工具返回的结果非常长（比如读一个大文件），直接塞回消息列表会撑爆上下文。解决办法是在 MCP server 层面做结果截断，或者在 agent 层面加结果摘要逻辑。

提示：MCP server 的日志默认可能不输出到终端，调试的时候建议把 server 的 stderr 重定向到文件，方便排查。

5.4 常见问题速查表

6. 工具选型与扩展：从能跑到好用

6.1 CLI 工具横向对比与选择建议

市面上 CLI agent 工具不少，选型的时候容易挑花眼。我把几个主流方向的特点列一下，方便对照自己的需求。

我的建议是：先用官方 CLI 跑通基本流程，理解 agent 执行逻辑，再根据痛点决定要不要自建。如果痛点只是"想换个模型"，可能改改配置就行；如果痛点是"要接一堆自定义工具"、"要精细控制成本"、"要集成到现有工作流"，那自建一套 treg 类的工具链是值得的。

6.2 从单 agent 到多 agent 的扩展路径

单 agent 跑通之后，下一步自然是多 agent 协作。但我要泼一盆冷水：多 agent 不是必须的，很多任务单 agent 加好工具就能解决。多 agent 带来的复杂度（通信、状态同步、错误传播）很容易超过收益。

如果确实需要多 agent，常见的模式有两种。一种是角色分工：planner agent 负责拆解任务，executor agent 负责执行，reviewer agent 负责检查。另一种是并行处理：多个 agent 同时处理不同子任务，最后汇总。前者适合有明确阶段划分的任务，后者适合可并行的独立子任务。

实现上，多 agent 可以共用同一套 MCP 工具层和 OpenRouter 路由层，只是每个 agent 有自己的 prompt 和模型配置。这样扩展成本相对可控。

6.3 安全边界与使用规范

最后必须强调安全边界。CLI agent 有本地执行能力，这意味着它能读写文件、执行命令、访问网络。权限控制是必须的，不能给 agent 无限制的本地访问。

几个实操原则：

• 工作目录限制。filesystem MCP server 启动时指定工作目录，agent 只能访问这个目录下的文件。
• 危险操作确认。删除文件、执行系统命令这类操作，加一层人工确认，不要全自动。
• 网络访问白名单。如果 agent 能访问网络，限制可访问的域名范围。
• 日志留痕。所有工具调用和执行结果都记日志，出问题能追溯。

我在实际使用中最大的体会是：agent 的能力边界要和你的信任边界匹配。你信任它做什么，就给它什么权限，不要图省事一次性全开。踩过几次坑之后，我现在所有 agent 项目默认都是最小权限启动，需要什么再加什么。

这套 CLI + OpenRouter + MCP 的组合，本质上是在"能力"和"可控"之间找平衡。OpenRouter 给你模型选择的自由，MCP 给你工具扩展的自由，CLI 给你执行入口的自由，而配置分层、权限控制、日志留痕这些工程实践，则是把自由约束在可控范围内的手段。把这条链路跑通一次，你对 agent 执行机制的理解会比看十篇概念文章都深。