“Bridge”是 OpenClaw 里最容易被误解的词之一。很多人会问Bridge 是一个服务吗 Bridge 是 Gateway 的一部分吗 Bridge 是模型适配器吗 Bridge 和 ACP、MCP、工具调用有什么关系答案有点反直觉今天讲 Bridge不能只讲一个名叫 Bridge 的进程。因为官方文档里历史上的 TCP Bridge 已经被移除当前版本不再启动 TCP bridge listenerbridge.*配置也不再是当前 schema 的一部分。现在应该优先使用 Gateway Protocol。所以这篇文章讲的 Bridge不是让你记一个旧组件而是让你理解 OpenClaw 里的“桥接层思维”把不同协议、运行时、工具系统和模型接口接到同一个 Agent loop 里。先说结论Bridge 是边界翻译层在 Agent 系统里很多东西天然说的不是一种语言。模型 说 token、messages、tool calls、responses Gateway 说 WebSocket frames、requests、events、sessions CLI / IDE 说 argv、stdio、ACP、JSON 工具 说 schema、参数、stdout、stderr、files 浏览器 说 tabs、DOM snapshot、click/type、screenshots Workspace 说 cwd、文件、上下文、边界Bridge 的核心价值就是翻译外部协议 ↓ OpenClaw 内部请求和事件 ↓ Agent Runtime 可理解的上下文、工具和状态如果没有桥接层Agent loop 会被每一种外部协议污染。有了桥接层Runtime 可以专心处理 prompt、context、model、tool loop而不同入口只要完成适配。先纠正一个历史误会TCP Bridge 已经是历史官方 Bridge protocol 页面明确提示TCP bridge 已经移除当前 OpenClaw build 不再提供 bridge listenerbridge.*配置也不在 schema 中。该页面保留为历史参考当前 node/operator client 应使用 Gateway Protocol。这点很重要。如果你在旧文章里看到bridge listener bridge.bind 18790 JSONL over TCP要把它当成历史设计而不是今天课程里要你配置的主路径。当前主路径更接近operator / node / CLI / web UI ↓ WebSocket Gateway Protocol Gateway ↓ Agent Runtime Tool Runtime也就是说本课讲 Bridge 的重点是“桥接职责”不是“旧 TCP Bridge 服务”。Bridge 层解决的第一个问题协议形状不同一个 IDE 可能使用 ACP。一个外部工具生态可能使用 MCP。一个 CLI 使用 argv、stdout、stderr。Gateway 使用 WebSocket JSON frames。模型 provider 使用各自的 chat/completions/responses API。这些协议的字段、生命周期、错误模型都不同。桥接层要做的是把它们映射成 OpenClaw 可以处理的内部对象external prompt → user message external session id → Gateway session key / session id external streaming delta → assistant stream event external cancel → abort run external tool request → OpenClaw tool invocation external resource / file → attachment or workspace file reference这就是为什么桥接层经常和“协议适配器”长得很像。Bridge 层解决的第二个问题运行环境不同Agent 可能运行在不同地方Gateway host Sandbox Node host macOS companion app IDE stdio process headless server每个环境的能力不同能不能读写宿主文件 能不能打开浏览器 能不能执行 shell 有没有 UI approval 有没有网络 cwd 是哪里 工具输出怎么返回桥接层必须把这些差异变成 Runtime 能理解的能力声明和执行结果。例如一个 node 连接 Gateway 时会声明角色、能力和命令浏览器插件会注册 browser toolsandbox 会改变工具执行的文件系统和进程边界。Agent Runtime 不应该在每一步都猜“我现在到底在哪台机器上”。它应该通过上下文和工具 schema 看到稳定能力。Bridge 层解决的第三个问题模型接口不同不同模型 provider 的接口并不完全一样。有的强调 messages。有的强调 responses。有的工具调用字段不同。有的支持特殊 thinking 参数。有的支持 multimodal input。如果 Runtime 直接依赖每个 provider 的原始字段系统会很快变乱。桥接思路是OpenClaw internal request ↓ provider adapter model-specific API call ↓ provider adapter OpenClaw internal assistant/tool event这样Agent loop 看见的是统一的assistant text tool call tool result usage finish reason error而不是被每个 provider 的差异拖着走。Bridge 层解决的第四个问题工具调用要可观察工具调用不是函数调用那么简单。它可能包含参数校验 权限检查 审批 sandbox 路由 执行中输出 超时 失败重试 结果裁剪 写入 transcript 流式事件展示所以工具桥接要同时服务两边对模型 提供清晰的 tool schema 和 tool result 对系统 提供可追踪的 tool lifecycle event这就是为什么第 10 讲提到的 streaming/tool events 和本讲的 Bridge 有关系。Bridge 不只是把工具结果塞回模型它还要把中间状态变成 Gateway、CLI、Dashboard、消息平台能理解的事件。ACP 是一种典型桥接官方openclaw acp文档说它通过 stdio 与 IDE 的 Agent Client Protocol 通信再通过 WebSocket 把 prompt 转发到 OpenClaw Gateway并保持 ACP sessions 与 Gateway session keys 的映射。这就是非常典型的桥IDE / ACP client ↓ stdio ACP openclaw acp ↓ WebSocket Gateway ↓ OpenClaw session / Agent Runtime它的职责不是把 OpenClaw 变成完整 IDE runtime。它做的是session 映射 prompt 转发 cancel 转发 基础 streaming update这很好地说明了桥接层的边界翻译和路由而不是包办所有执行。MCP 也是桥接但方向不同MCP 常见于“把外部工具暴露给 Agent”。如果 ACP 更像“让外部客户端进入 OpenClaw”那么 MCP 更像“让 OpenClaw 进入外部工具生态”。可以这样对比ACP IDE/client → OpenClaw 重点是 session、prompt、stream、cancel MCP OpenClaw → external tool/resource server 重点是 tool、resource、prompt、capability discovery两者都属于桥接。只不过桥接方向不同。一个真实场景假设你在 IDE 里使用 ACP把一个问题发给 OpenClaw请读取当前项目的错误日志并生成修复建议。链路可能是IDE ↓ ACP prompt openclaw acp bridge ↓ Gateway WebSocket agent request Gateway ↓ session routing Agent Runtime ↓ context model tools Tool Runtime ↓ read / exec / browser Agent Runtime ↓ final answer Gateway ↓ stream events openclaw acp bridge ↓ ACP updates IDE用户看到的是 IDE 里的回答。但系统实际经过了 ACP、Gateway Protocol、Session、Runtime、Tool、Stream 多层翻译。这就是 Bridge 的价值。常见误解误解一Bridge 就是旧 TCP Bridge不是。旧 TCP Bridge 已经是历史参考。当前应该把 Bridge 理解成协议和运行时之间的翻译层主路径是 Gateway Protocol。误解二Bridge 越多越好不是。桥接层越多错误映射、状态重复和延迟也越多。好的设计是边界清晰、职责单一、事件可追踪。误解三Bridge 可以忽略安全边界不能。桥接层经常跨越协议和环境因此更需要保留身份、session、权限、审批和 sandbox 信息。误解四Bridge 只处理输入不是。它也处理输出streaming delta、tool event、error、cancel、final response 都需要被翻译回外部协议。最后总结Bridge 是连接不同系统边界的翻译层。今天的 OpenClaw 不应该再按旧 TCP Bridge 来理解而应该按 Gateway Protocol、ACP、MCP、tool adapter、provider adapter、runtime adapter 这些桥接职责来理解。一句话总结Bridge 让 OpenClaw 可以把不同入口、协议、模型、工具和运行环境接入同一个 Agent loop。本节作业用一张图画出 ACP client 到 Gateway session 的映射链路。解释为什么旧 TCP Bridge 不是当前主路径。对比 ACP 和 MCP 的桥接方向。列出一次工具调用中需要桥接的 5 种信息。思考Bridge 层如果丢失 session id会导致什么问题下一节预告下一节讲Workspace文件系统、项目上下文和执行边界我们会解释 workspace 为什么既是上下文来源也是工具执行的默认 cwd但它本身并不等于安全沙箱。参考资料OpenClaw DocsBridge protocolOpenClaw DocsGateway protocol / Gateway architectureOpenClaw DocsACP CLIOpenClaw DocsCLI referenceOpenClaw DocsAgent loop原文链接Bridge连接模型、工具和运行环境的中间层 | Harries Blog™
Bridge：连接模型、工具和运行环境的中间层
发布时间：2026/6/5 11:46:49
“Bridge”是 OpenClaw 里最容易被误解的词之一。很多人会问Bridge 是一个服务吗 Bridge 是 Gateway 的一部分吗 Bridge 是模型适配器吗 Bridge 和 ACP、MCP、工具调用有什么关系答案有点反直觉今天讲 Bridge不能只讲一个名叫 Bridge 的进程。因为官方文档里历史上的 TCP Bridge 已经被移除当前版本不再启动 TCP bridge listenerbridge.*配置也不再是当前 schema 的一部分。现在应该优先使用 Gateway Protocol。所以这篇文章讲的 Bridge不是让你记一个旧组件而是让你理解 OpenClaw 里的“桥接层思维”把不同协议、运行时、工具系统和模型接口接到同一个 Agent loop 里。先说结论Bridge 是边界翻译层在 Agent 系统里很多东西天然说的不是一种语言。模型 说 token、messages、tool calls、responses Gateway 说 WebSocket frames、requests、events、sessions CLI / IDE 说 argv、stdio、ACP、JSON 工具 说 schema、参数、stdout、stderr、files 浏览器 说 tabs、DOM snapshot、click/type、screenshots Workspace 说 cwd、文件、上下文、边界Bridge 的核心价值就是翻译外部协议 ↓ OpenClaw 内部请求和事件 ↓ Agent Runtime 可理解的上下文、工具和状态如果没有桥接层Agent loop 会被每一种外部协议污染。有了桥接层Runtime 可以专心处理 prompt、context、model、tool loop而不同入口只要完成适配。先纠正一个历史误会TCP Bridge 已经是历史官方 Bridge protocol 页面明确提示TCP bridge 已经移除当前 OpenClaw build 不再提供 bridge listenerbridge.*配置也不在 schema 中。该页面保留为历史参考当前 node/operator client 应使用 Gateway Protocol。这点很重要。如果你在旧文章里看到bridge listener bridge.bind 18790 JSONL over TCP要把它当成历史设计而不是今天课程里要你配置的主路径。当前主路径更接近operator / node / CLI / web UI ↓ WebSocket Gateway Protocol Gateway ↓ Agent Runtime Tool Runtime也就是说本课讲 Bridge 的重点是“桥接职责”不是“旧 TCP Bridge 服务”。Bridge 层解决的第一个问题协议形状不同一个 IDE 可能使用 ACP。一个外部工具生态可能使用 MCP。一个 CLI 使用 argv、stdout、stderr。Gateway 使用 WebSocket JSON frames。模型 provider 使用各自的 chat/completions/responses API。这些协议的字段、生命周期、错误模型都不同。桥接层要做的是把它们映射成 OpenClaw 可以处理的内部对象external prompt → user message external session id → Gateway session key / session id external streaming delta → assistant stream event external cancel → abort run external tool request → OpenClaw tool invocation external resource / file → attachment or workspace file reference这就是为什么桥接层经常和“协议适配器”长得很像。Bridge 层解决的第二个问题运行环境不同Agent 可能运行在不同地方Gateway host Sandbox Node host macOS companion app IDE stdio process headless server每个环境的能力不同能不能读写宿主文件 能不能打开浏览器 能不能执行 shell 有没有 UI approval 有没有网络 cwd 是哪里 工具输出怎么返回桥接层必须把这些差异变成 Runtime 能理解的能力声明和执行结果。例如一个 node 连接 Gateway 时会声明角色、能力和命令浏览器插件会注册 browser toolsandbox 会改变工具执行的文件系统和进程边界。Agent Runtime 不应该在每一步都猜“我现在到底在哪台机器上”。它应该通过上下文和工具 schema 看到稳定能力。Bridge 层解决的第三个问题模型接口不同不同模型 provider 的接口并不完全一样。有的强调 messages。有的强调 responses。有的工具调用字段不同。有的支持特殊 thinking 参数。有的支持 multimodal input。如果 Runtime 直接依赖每个 provider 的原始字段系统会很快变乱。桥接思路是OpenClaw internal request ↓ provider adapter model-specific API call ↓ provider adapter OpenClaw internal assistant/tool event这样Agent loop 看见的是统一的assistant text tool call tool result usage finish reason error而不是被每个 provider 的差异拖着走。Bridge 层解决的第四个问题工具调用要可观察工具调用不是函数调用那么简单。它可能包含参数校验 权限检查 审批 sandbox 路由 执行中输出 超时 失败重试 结果裁剪 写入 transcript 流式事件展示所以工具桥接要同时服务两边对模型 提供清晰的 tool schema 和 tool result 对系统 提供可追踪的 tool lifecycle event这就是为什么第 10 讲提到的 streaming/tool events 和本讲的 Bridge 有关系。Bridge 不只是把工具结果塞回模型它还要把中间状态变成 Gateway、CLI、Dashboard、消息平台能理解的事件。ACP 是一种典型桥接官方openclaw acp文档说它通过 stdio 与 IDE 的 Agent Client Protocol 通信再通过 WebSocket 把 prompt 转发到 OpenClaw Gateway并保持 ACP sessions 与 Gateway session keys 的映射。这就是非常典型的桥IDE / ACP client ↓ stdio ACP openclaw acp ↓ WebSocket Gateway ↓ OpenClaw session / Agent Runtime它的职责不是把 OpenClaw 变成完整 IDE runtime。它做的是session 映射 prompt 转发 cancel 转发 基础 streaming update这很好地说明了桥接层的边界翻译和路由而不是包办所有执行。MCP 也是桥接但方向不同MCP 常见于“把外部工具暴露给 Agent”。如果 ACP 更像“让外部客户端进入 OpenClaw”那么 MCP 更像“让 OpenClaw 进入外部工具生态”。可以这样对比ACP IDE/client → OpenClaw 重点是 session、prompt、stream、cancel MCP OpenClaw → external tool/resource server 重点是 tool、resource、prompt、capability discovery两者都属于桥接。只不过桥接方向不同。一个真实场景假设你在 IDE 里使用 ACP把一个问题发给 OpenClaw请读取当前项目的错误日志并生成修复建议。链路可能是IDE ↓ ACP prompt openclaw acp bridge ↓ Gateway WebSocket agent request Gateway ↓ session routing Agent Runtime ↓ context model tools Tool Runtime ↓ read / exec / browser Agent Runtime ↓ final answer Gateway ↓ stream events openclaw acp bridge ↓ ACP updates IDE用户看到的是 IDE 里的回答。但系统实际经过了 ACP、Gateway Protocol、Session、Runtime、Tool、Stream 多层翻译。这就是 Bridge 的价值。常见误解误解一Bridge 就是旧 TCP Bridge不是。旧 TCP Bridge 已经是历史参考。当前应该把 Bridge 理解成协议和运行时之间的翻译层主路径是 Gateway Protocol。误解二Bridge 越多越好不是。桥接层越多错误映射、状态重复和延迟也越多。好的设计是边界清晰、职责单一、事件可追踪。误解三Bridge 可以忽略安全边界不能。桥接层经常跨越协议和环境因此更需要保留身份、session、权限、审批和 sandbox 信息。误解四Bridge 只处理输入不是。它也处理输出streaming delta、tool event、error、cancel、final response 都需要被翻译回外部协议。最后总结Bridge 是连接不同系统边界的翻译层。今天的 OpenClaw 不应该再按旧 TCP Bridge 来理解而应该按 Gateway Protocol、ACP、MCP、tool adapter、provider adapter、runtime adapter 这些桥接职责来理解。一句话总结Bridge 让 OpenClaw 可以把不同入口、协议、模型、工具和运行环境接入同一个 Agent loop。本节作业用一张图画出 ACP client 到 Gateway session 的映射链路。解释为什么旧 TCP Bridge 不是当前主路径。对比 ACP 和 MCP 的桥接方向。列出一次工具调用中需要桥接的 5 种信息。思考Bridge 层如果丢失 session id会导致什么问题下一节预告下一节讲Workspace文件系统、项目上下文和执行边界我们会解释 workspace 为什么既是上下文来源也是工具执行的默认 cwd但它本身并不等于安全沙箱。参考资料OpenClaw DocsBridge protocolOpenClaw DocsGateway protocol / Gateway architectureOpenClaw DocsACP CLIOpenClaw DocsCLI referenceOpenClaw DocsAgent loop原文链接Bridge连接模型、工具和运行环境的中间层 | Harries Blog™
