你有没有发现当前 AI Agent 调用一个网站的能力时还停留在“爬虫时代”先抓 HTML再解析 DOM遇到反爬机制就得绕页面改版就要重写解析器。这不是智能只是在更高效地拆网页。真正合理的做法应该是网站主动把能力“递”到 Agent 面前告诉它我这里有一个查询订单、搜索商品、发送消息的工具你可以直接调用。这正是 WebMCP 这个新协议试图解决的问题。这篇文章要聊的内容包含三层第一WebMCP 和 MCP 有什么区别它为什么值得网站开发者和 AI 应用开发者同时关注第二OpenAI Codex 进入 Chrome 侧边栏之后Agent 工作台长什么样怎么把 Codex CLI 接到浏览器里第三按一条最小路径走通“网站暴露工具 → 浏览器 Agent 调用工具”的完整链路并给出常见报错排查。如果说 2025 年是 Agent 框架百花齐放的一年那接下来很快会进入“Agent 与 Web 基础设施重新连接”的阶段。WebMCP 是其中一个重要的方向而 Codex 进入浏览器侧边栏又是另一个信号。这两件事拼在一起结果是Agent 不再只能聊天它会成为真正能使用 Web 服务的操作员。1. 这篇文章真正要解决的问题很多开发者对 Agent 的现状有一个明显困惑Agent 框架越来越多能接的模型越来越多但 Agent 真正能“做”的事情依然很有限。问题出在哪不是模型理解能力不够而是 Agent 与外部服务之间的连接方式太原始。传统做法是给 Agent 配工具工具背后是 API。但 API 的发现成本很高网站需要额外开发、维护、鉴权、限流Agent 也需要知道这个工具长什么样、参数是什么、返回什么结构。更麻烦的是大多数普通网站根本没有 APIAgent 只能靠浏览器自动化点来点去或者靠爬虫抓取页面。整个过程既脆弱又低效。WebMCP 想改变的是这件事让网站像发布一个“协议文件”一样把自己可被 Agent 调用的工具暴露出来。Agent 访问网站时先读取这个协议文件了解网站提供哪些能力然后按标准格式调用。这有点像 20 年前的 WSDL也像 Web 服务时代的 OpenAPI只不过服务对象从“开发者”变成了“AI Agent”。所以如果你正在做以下事情中的任何一件这篇文章值得读完你有一个网站希望 AI Agent 能直接使用站内功能但还不知道怎么设计工具暴露层。你在用 Codex CLI 做编程 Agent想把它接入 Chrome 侧边栏提升在网页上下文里跑任务的效率。你想搞清楚 MCP 和 WebMCP 的边界避免在新一波协议浪潮里踩概念坑。本文不会把这套东西包装成“划时代”的神话而是尽量落到工程细节协议如何设计、代码怎么写、插件怎么配、报错怎么查。2. 从 MCP 到 WebMCPAgent 连接 Web 的方式正在改变在聊 WebMCP 之前必须先说清楚 MCP。MCP 的完整名称是 Model Context Protocol它的目标是让 AI 模型与应用环境之间建立一套标准化的工具调用协议。你可以把 MCP 理解为“AI 世界的 USB 接口”模型不需要知道某个工具的内部实现只要按照标准格式发送请求就能调用文件系统、数据库、代码仓库、消息服务等能力。MCP 解决的核心问题是“工具接入的碎片化”。没有 MCP 之前每个 Agent 框架都要自己定义一套工具调用格式模型要会读各种各样的工具描述。有了 MCP工具仓库就是一组符合统一规范的接口Agent 天然可以消费。2.1 WebMCP 与 MCP 的区别从名字看WebMCP 像是“Web 版的 MCP”。但严格来说它和 MCP 解决的不是同一个问题。MCP 关心的是“Agent 已经连上一个服务之后怎么调用它的工具”偏向本地和私有环境的资源连接。WebMCP 关心的是“Agent 在开放互联网上发现一个网站时怎么知道这个网站有哪些能力可以被调用”偏向 Web 场景的能力发现与暴露。可以这样对比维度MCPWebMCP核心问题工具连接规范网站能力发现与暴露服务对象已接入 Agent 的本地或远程服务面向开放互联网的网页服务典型场景连数据库、连文件系统、连企业应用网站主动声明可被 Agent 调用的工具与网页关系不依赖网页通常以网页域名或站点为边界发展阶段已有不少实现和 SDK方向明确规范还在演进这里要避免一个常见误区WebMCP 不是“用 AI 直接生成网页”也不是“网页爬取协议的升级版”。爬虫还是让 Agent 去读页面内容而 WebMCP 是让网站直接给 Agent 提供结构化工具入口。可以理解为“网站从被读的对象变成了被调用的服务”。2.2 WebMCP 的典型工作流程一个典型的 WebMCP 场景大概是这样的网站运营者想开放站内某个功能给 AI Agent 使用比如订单查询、商品搜索、天气查询、航班状态查询。网站在一个约定的路径下发布描述文件例如/.well-known/webmcp.json里面写清楚这个网站支持哪些工具、工具的参数、调用入口和认证方式。Agent 需要处理某个任务时发现这个网站并读取描述文件理解它提供的能力。Agent 根据描述文件构建请求在获得用户授权后调用网站暴露的工具接口。网站返回结构化结果Agent 再结合模型能力生成最终答案。这套流程之所以重要是因为它把“让 Agent 学会使用网站”的成本从“写解析器”变成了“写工具声明”。网站方可以控制暴露什么、不暴露什么可以加鉴权、限流、审计比反爬对抗要健康得多。当然WebMCP 还处于早期具体规范可能调整。但趋势已经能看清楚网站和 Agent 之间会形成一种新的“服务契约”谁先把契约做清楚谁就能在 Agent 生态里被优先使用。3. Codex 与 Chrome 侧边栏一套 Agent 工作台的拼图如果说 WebMCP 解决的是“Agent 怎么用网站”那 Codex 进入 Chrome 侧边栏解决的是“人类怎么和 Agent 协作”。Codex 是 OpenAI 推出的编程智能体工具它可以理解整个代码仓库执行命令运行测试修改代码。Codex CLI 的优势在于它以命令行为入口非常适合接入各种开发工具链比如 IDE、终端、CI 脚本甚至浏览器插件。3.1 为什么侧边栏很重要浏览器侧边栏是容易被低估的 Agent 入口。当你打开一个网页看到的不只是文字和图片还有上下文当前页面的内容、当前登录的账号、当前 URL 所属的站点。如果 Agent 只能在一个独立聊天窗口里工作它其实看不到这些上下文任务会变得很难落地。Chrome 侧边栏插件的作用是让 Agent 直接驻留当前浏览场景。它可以读取当前页面标题和文本内容配合 Codex CLI 的终端执行能力在页面上下文里继续写代码、查资料、跑命令。一个典型场景你在浏览一个开源项目的 README想让 Agent 基于这个项目初始化一个本地 Demo。传统做法是手动复制项目地址到终端然后写命令。有了侧边栏 Codex你可以直接选中页面内容输入“读取这个项目的初始化文档按步骤在当前目录创建 Demo”Agent 就能结合网页内容和本地命令能力完成。3.2 它不是网页版 ChatGPT最容易出现的误解是把这个插件当成“网页版 ChatGPT”。实际上侧边栏里的 Codex 是一个 Agent 前端背后连接的是 Codex CLI 或兼容服务。它的价值不在于“和模型聊天”而在于“让模型在真实开发环境里干活”。因此在使用前要理解这些技术组件Codex CLI负责执行任务、管理上下文、调用模型、运行命令。Codex CLI 配置文件定义模型、API 端点、认证信息、沙箱规则。Chrome 侧边栏插件提供浏览器 UI并负责找到 Codex CLI 的路径。模型服务可以是 OpenAI 官方 API也可以是兼容 OpenAI 接口的网关或本地服务。组件之间的关系是你在侧边栏输入任务插件将任务交给 Codex CLICodex CLI 调用模型并执行工具命令最终把结果回报到侧边栏。3.3 Codex 进入侧边栏意味着什么如果你的浏览器里驻留着一个能执行命令的 Agent那么网页浏览和本地开发之间的墙会被打破。过去浏览器里的信息要想进入开发环境靠人复制粘贴未来 Agent 可以直接读取页面生成代码运行测试再把结果写回页面。这同时也是 Agent 工具链走向“分布式工作台”的标志不再只有一个大而全的 Agent 应用而是由 CLI、浏览器插件、IDE 插件、网页 MCP 服务共同构成一套工作环境。Codex 进入 Chrome 侧边栏只是其中一块拼图。4. 环境准备与前置条件下面进入实操部分。为了让“网站暴露工具”和“浏览器侧边栏调用 Codex”这两条链路都能跑起来先准备好环境。本节列出的版本要求以通用环境为准。具体版本请以官方 README 和你的实际系统为准不要照搬未知的固定版本号。4.1 基础环境建议使用 macOS 或 LinuxWindows 也可以但需要额外注意 PATH 和 shell 配置。你的机器上需要Node.js 16 或更高版本用于安装和运行 Codex CLI 相关工具。Python 3.9 或更高版本用于运行 WebMCP 示例服务。Chrome 浏览器用于安装侧边栏插件建议使用稳定版。一个可用的 API Key 或可访问的 API 端点用于让 Codex 调用大模型。在没有 API Key 的情况下一些兼容 OpenAI 协议的本地服务也可以作为实验环境但需要自行保证服务和模型配置正确。重点先把链路走通再考虑生产级配置。4.2 检查 Node.js 和 Python在终端里执行node -v npm -v python3 --version如果node -v报错请先安装 Node.js。如果python3 --version报错请先安装 Python 3。这一步很简单但很多后续报错都源于版本缺失。4.3 安装 Codex CLICodex CLI 的安装方式在不同时期有差异最稳妥的方式是以 OpenAI Codex 项目仓库的 README 为准。推荐使用 npm 全局安装因为这样更容易被浏览器插件找到可执行文件。npm install -g openai/codex安装完成后验证可执行文件codex --version如果终端提示codex: command not found说明 npm 的全局 bin 目录没有加到 PATH。可以通过npm prefix -g查看全局安装目录再把对应的 bin 目录加入 PATH。Codex 首次运行时通常需要登录或配置 API Key。执行codex login这里会根据官方提示完成认证流程。如果你使用的是 API Key通常在配置文件或环境变量中设置。注意不要在公共屏幕上泄露 Key。4.4 准备 WebMCP 示例服务为了演示网站如何暴露工具我会用 FastAPI 写一个最小的 WebMCP 服务。先安装依赖pip install fastapi uvicorn pydantic这个服务不需要数据库不需要外部依赖只提供一个订单查询工具示例。先跑通再替换成你自己的业务逻辑。5. 核心流程拆解让网站通过 WebMCP 暴露工具现在我们拆解“网站主动暴露工具给 AI Agent”的最小实现路径。整体分四步设计工具、写工具描述文件、实现调用端点、验证发现与调用。5.1 设计工具第一步不是写代码而是想清楚你要暴露什么。一个工具描述应该包含至少三部分工具名称机器可读的字符串例如get_order_status。输入参数描述结构化地描述参数类型和必填项通常用 JSON Schema。调用端点实际接收请求的 HTTP 地址。建议一开始只暴露一个工具这样容易排查问题。等到链路通了再逐步增加工具。5.2 编写 WebMCP 描述文件假设你运营一个电商站想让 Agent 能查询订单状态。那么你可以在网站的/.well-known/webmcp.json路径下放一个描述文件。下面是一个演示用的描述结构。它不代表某个已经定稿的标准只是还原 WebMCP 可能的样子目的是让你理解网站如何“声明”能力。{ name: example-shop, version: 1.0.0, tools: [ { name: get_order_status, description: 查询订单状态, inputSchema: { type: object, properties: { order_id: { type: string, description: 订单号 } }, required: [order_id] }, endpoint: /webmcp/tools/get_order_status } ] }把这个 JSON 文件保存到服务器的/.well-known/webmcp.json。之后Agent 通过https://example.com/.well-known/webmcp.json就能发现这个网站暴露的工具。需要注意实际协议里可能还会有认证、请求方法、返回格式等字段。这里只保留最核心的部分演示重点是“声明-发现-调用”的逻辑。5.3 实现调用端点有了描述文件还需要一个真正能处理请求的 HTTP 接口。下面用 FastAPI 写一个最小服务既返回描述文件也提供工具调用端点。# webmcp_server.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class OrderRequest(BaseModel): order_id: str app.get(/.well-known/webmcp.json) def get_manifest(): return { name: example-shop, version: 1.0.0, tools: [ { name: get_order_status, description: 查询订单状态, inputSchema: { type: object, properties: { order_id: { type: string, description: 订单号 } }, required: [order_id] }, endpoint: /webmcp/tools/get_order_status } ] } app.post(/webmcp/tools/get_order_status) def get_order_status(req: OrderRequest): # 实际项目中这里应该查询数据库或调用内部订单服务 # 返回结构最好保持稳定方便 Agent 解析 return { order_id: req.order_id, status: paid, updated_at: 2026-01-01T12:00:00Z }这段代码的关键在于/.well-known/webmcp.json路由负责“声明工具”让 Agent 知道这里有什么可用。/webmcp/tools/get_order_status路由负责“执行业务逻辑”返回结构化数据。返回结构保持稳定Agent 不需要从自然语言文本里猜结果。5.4 启动服务并验证在终端里启动 FastAPI 服务uvicorn webmcp_server:app --reload --port 8000先用 curl 请求描述文件确认它可访问curl http://localhost:8000/.well-known/webmcp.json预期会看到 JSON 格式的工具描述。再模拟 Agent 调用工具curl -X POST http://localhost:8000/webmcp/tools/get_order_status \ -H Content-Type: application/json \ -d {order_id: 20260101001}预期返回{order_id:20260101001,status:paid,updated_at:2026-01-01T12:00:00Z}到这里“网站暴露工具给 Agent 调用”的最小闭环已经完成。5.5 从单个工具到一组工具真实网站不可能只有一个工具。当工具多起来维护描述文件会变得麻烦。建议用代码生成描述文件而不是手写大 JSON。比如把工具定义放在 Python 字典或数据类里再自动渲染成 JSON。这样能避免“描述文件更新了端点却没实现”的错位问题。同时每个工具都应该有独立的错误码。Agent 是人机交互的一部分错误处理越结构化Agent 越能基于错误信息调整下一步操作。6. Chrome 侧边栏接入 Codex配置、启动与验证这部分我们解决另一个问题Agent 工作台怎么接到浏览器侧边栏。6.1 安装并定位 Codex CLI浏览器插件通常要求配置codex_cli_path也就是 Codex CLI 可执行文件的路径。这个配置项非常容易踩坑因为插件本身不感知 Shell 环境。先找到 Codex 的安装位置which codex在 macOS 上常见结果可能是/opt/homebrew/bin/codex或~/.npm-global/bin/codex。在 Linux 上可能是/usr/local/bin/codex。记住这个路径后面要用。如果which codex没有输出说明 Codex 没有安装成功或者 npm 全局目录不在 PATH 中。先解决 PATH 问题再继续配置插件。6.2 配置 Codex CLICodex 支持配置文件常见位置是~/.codex/config.toml。配置文件的作用是声明模型、API 端点、认证等参数。下面是一个示例配置文件字段名以实际版本为准这里主要演示配置结构model gpt-5-codex [api] base_url https://api.openai.com/v1如果你的环境使用的是兼容 OpenAI 协议的网关服务把base_url替换成网关地址即可。如果你使用 API Key避免直接写入config.toml推荐通过环境变量或者系统密钥链管理。修改配置后在终端里跑一个简单任务确认 Codex 能正常工作codex exec print hello如果出现 “model not supported” 这类错误说明当前模型不适用于 Codex。请查阅官方支持的模型列表换成受支持的基础模型。6.3 安装 Chrome 侧边栏插件在 Chrome 应用商店找到 OpenAI Codex 相关插件安装后浏览器右上角会出现对应图标。进入插件设置一般会看到Codex CLI 路径填写上一步which codex得到的路径。工作目录建议填写一个独立的项目目录。模型/服务端点如果插件直接暴露了模型配置可以使用默认值或与 Codex CLI 配置保持一致。配置完成后打开侧边栏点击连接或初始化。插件应当能检测到 Codex CLI。如果界面上一直提示Unable to locate the codex CLI binary. Set codex_cli_path or ensure the executable is in PATH说明插件没找到 Codex。你需要回到设置把codex_cli_path填写为完整路径然后重启插件面板。6.4 侧边栏任务示例我们用一个实际任务来验证链路打开任意一个技术文档页面让侧边栏 Codex 读取当前页面内容并用三句话概括文档要点。操作步骤打开一个技术文档页面。在侧边栏输入“总结当前页面的主要内容”。观察 Codex 是否读取页面内容并返回结果。这里有个重点要让 Codex 看到网页内容插件需要具备提取当前页面文本的能力。不同的插件实现方式不同有的会直接把页面文本拼进提示词有的会让 Agent 调用浏览器工具。你需要根据插件界面提示确认它使用的是哪种模式。如果 Agent 返回“没有看到页面内容”可能是插件没有授予读取当前页面权限或者页面是纯 JS 渲染文本提取不到。可以尝试在侧边栏选中部分文本再发起任务。6.5 验证命令执行能力侧边栏 Codex 的另一个关键价值是能执行本地命令。可以输入在当前项目目录下创建一个 example.py 文件内容为打印当前时间。如果 Codex 正常执行它会在工作目录创建文件并反馈执行结果。这是在浏览器里间接操作本地开发环境的一种方式。使用时要特别留意命令执行的权限边界不要让它直接跑未经审查的命令。7. 常见问题与排查思路结合 Codex CLI、Chrome 插件和 WebMCP 示例服务的常见问题整理成下面这个表格。问题现象可能原因排查方式解决方案codex: command not foundnpm 全局 bin 目录不在 PATH 中执行npm prefix -g查看全局目录将 bin 目录加入 PATH或使用完整路径Unable to locate the codex CLI binary插件配置的codex_cli_path不正确在终端执行which codex填写正确的完整路径重启插件登录后仍然鉴权失败API Key 未设置或已过期检查环境变量、配置文件、密钥链重新执行登录或更新 API Keymodel not supported when using codex配置了 Codex 不支持的模型查看当前模型和官方支持列表更换为受支持的模型cc switch local proxy failed while handling codex endpoint /responses本地代理或网络切换导致请求端点异常检查代理配置、网络环境、日志中的 endpoint切换回稳定网络或调整本地代理设置不要直接忽略该报错WebMCP 描述文件 404文件路径不对或服务未启动curl http://localhost:8000/.well-known/webmcp.json确认路由路径和服务端口工具调用返回 405请求方法不匹配检查描述文件里的 endpoint 方法确保使用 POST 调用工具端点Agent 读不到网页内容插件未获取当前页面权限或页面是动态渲染选中文本后重试检查插件权限开启页面读取权限优先对静态页面测试API 请求超时网络缓慢或模型推理时间过长检查日志和响应时间调整模型参数确认网络稳定后再试这里特别想提醒一个点cc switch local proxy failed while handling codex endpoint /responses这类报错看起来像“本地代理切换失败”。但不要急着去改全局代理先看日志里具体请求到了哪个 endpoint以及报错是发生在请求前还是响应后。很多时候是环境切换后Codex 仍然拿着旧的连接信息重启 Codex 进程就能解决。8. 最佳实践与工程建议协议还处于演进期一旦要在真实项目里使用 WebMCP 和 Codex不能只追求“能跑通”。下面这些建议来自工程化视角希望你少踩坑。8.1 工具暴露的安全边界WebMCP 让网站“主动暴露工具”但暴露本身就有风险。对外开放的每一个工具都要经过独立的风险评估。最小权限原则同样适用于 Agent 工具层。不要让一个查询订单接口顺手返回用户的手机号。更合理的做法是工具返回 Agent 完成任务所需的最小字段并隐去敏感信息。认证上优先采用短期令牌配合用户授权流程。不要让 Agent 长期持有高权限凭证。每次调用前网站应确认这个 Agent 是否获得了当前用户的实际授权。8.2 为每个工具设计结构化错误Agent 不像人那样能从错误页面的长篇文本里找到关键信息。工具接口应使用结构化的错误响应比如{ error: { code: ORDER_NOT_FOUND, message: 订单不存在 } }结构化错误码能让 Agent 快速判断是参数问题、权限问题还是业务问题。不要把所有异常都返回成统一的500 Internal Server Error对 Agent 来说这既不可解释也不可恢复。8.3 保持描述文件与实现的一致性工具描述文件是“承诺”接口实现是“履约”。如果描述文件说参数必填order_id但接口实际允许空值Agent 就会产生错误预期。建议在 CI 里增加一个校验任务自动检查描述文件中的每个工具是否都有对应的路由实现。这个校验逻辑不复杂但能避免很多上线后才发现的低级问题。8.4 Codex 接入生产环境的注意事项不要把个人 API Key 直接写在插件配置里尤其是分享屏幕或提交到代码仓库时。推荐的做法是使用系统的密钥链管理服务或配置环境变量。Codex 能够执行本地命令这既是能力也是风险。在团队协作环境里建议开启命令审批机制让 Agent 在执行修改性命令前先征求人的确认。即使个人使用也尽量把它限制在一个专用工作目录中避免它随意读写系统文件。同时LLM 的输出具有不确定性。Codex 生成的代码、命令和结论不能直接视为正确结果。一定要在本地或 CI 里跑测试验证。Agent 是加速器不是裁判员。8.5 记录 Agent 调用链生产环境里运行 WebMCP 服务一定要记录完整的调用链包括哪个 Agent 调用了哪个工具、传了什么参数、返回了什么结果、耗时多久、用户是否授权。不要只记请求日志。要能把一次用户问题关联到 Agent 的多次工具调用。否则一旦出现问题很难定位是模型理解错了还是工具实现错了。8.6 先跑通再扩大范围第一版 WebMCP 服务建议只暴露一个低风险工具比如“查询公开商品信息”。先验证 Agent 能发现、能调用、能解析返回结果再逐步增加订单、支付、消息等高权限工具。这种做法能控制风险也能让团队逐步积累 Agent 工具的设计经验。不要一开始就做几十个工具那只会让调试变得无比痛苦。9. 总结与后续学习方向WebMCP 真正值得关注的点不是它又发明了一个新名词而是它把 Agent 与网站的关系从“侵入式读取”变成了“服务式调用”。网站可以用标准方式声明能力Agent 可以标准方式消费能力。这对网站方和 AI 应用方都有价值。Codex 进入 Chrome 侧边栏则可以看作 Agent 工作台交互形态的一次变化Agent 不再只活在终端或 IDE 里它开始进入浏览器这个信息密度最高的入口。配合 WebMCP未来的浏览器 Agent 也许能真正“用它看到的网站”而不是“抓取它看到的网站”。如果你想把这次学习落成实践建议按下面的顺序走一遍用 FastAPI 写一个最小 WebMCP 服务暴露一个查询类工具。配置好 Codex CLI跑通一个本地任务。安装 Chrome 侧边栏插件把codex_cli_path配好验证页面总结和命令执行。尝试把 WebMCP 工具描述文件接入你的真实网站先在测试环境观察 Agent 调用行为。在协议和工具版本都不稳定的阶段最重要的不是追每一个新发布而是掌握“描述 → 发现 → 调用 → 验证 → 审计”这条链路。WebMCP 和 Codex 都在快速迭代但只要理解了这条链路未来协议怎么变动你都能快速接上。