企业官网建设流程全解析

Agent Zero A0 CLI Connector 实战指南：让 Docker 中的 Agent Zero 安全操作宿主机终端与浏览器

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

A0 CLI Connector 是 Agent Zero 与宿主机之间的"有意为之的桥"：Agent Zero 依旧运行在 Docker 容器中负责思考、记忆与调用工具，而 A0 CLI 安装在宿主机上，把宿主机的真实文件、终端与 Chrome 系浏览器变成 Agent Zero 可用的工具。阅读本文后，你将掌握 A0 CLI 的安装、连接、功能键与斜杠命令、Host Browser（自带浏览器）配置，以及它背后的 WebSocket 连接器协议与远程工具实现原理，能在自己的电脑上安全地让 Agent Zero 操作真实环境。

架构定位：A0 CLI 是门，不是第二个 Agent

A0 CLI 不是第二个智能体。Agent Zero 仍然是那个负责思考、记忆和使用工具的实体，A0 CLI 只是让 Agent Zero 得以在运行 CLI 的那台电脑上工作的"门口"。这个设计源于安全与可管理性的取舍：

• Agent Zero 住在 Docker 里，因为这样更安全、更容易管理；
• A0 CLI 装在宿主机上，是你在想让 Agent Zero 处理真实文件、真实终端或真实浏览器时使用的"有意的桥"；
• 同一个连接器还可以让 Agent Zero 使用你电脑上的 Chrome 系浏览器（即 Host Browser 模式）。

从仓库源码看，这个连接能力由内置插件_a0_connector承载。其元数据（plugin.yaml）显示插件名称为_a0_connector、标题为 "A0 Connector"，版本1.5，作用是通过 HTTP 加/wsWebSocket 集成，使用会话认证（session auth），并通过auth.handlers激活处理器。插件内部的 AGENTS.md 明确列出了各目录的职责：api/负责连接器的 WebSocket 与 API 入口，helpers/负责聊天上下文、事件桥、执行配置等运行时辅助，tools/、prompts/、skills/负责面向 Agent 与 UI 的贡献。

快速安装

macOS / Linux 宿主机终端：

curl -LsSf https://cli.agent-zero.ai/install.sh | sh

Windows（PowerShell）：

irm https://cli.agent-zero.ai/install.ps1 | iex

务必在宿主机上运行，而不是在 Agent Zero 容器内部。安装器会自行处理所需的小型 Python 辅助环境。仓库中配套的setup-a0-cliSkill（SKILL.md）也印证了这一点：如果用户位于/a0、docker exec或其他容器 shell 内，应先退出，在正常的电脑终端中运行安装器，绝不在容器里执行安装命令。若安装后找不到a0命令，请新开一个终端再试。

连接并开始工作

1. 确保 Agent Zero 已经运行。
2. 在宿主机上启动 A0 CLI：

a0

3. 如果 Agent Zero 运行在同一台机器上，A0 CLI 通常会通过本地 Docker 发现自动找到它。
4. 如果 Agent Zero 在其他机器上，手动输入其 Web 地址。
5. 打开或创建一个聊天，确认你可以在宿主机上与 Agent Zero 对话。

[!NOTE] 如果 A0 CLI 提示缺少连接器支持（connector support is missing），请先更新 Agent Zero。从源码看，连接器 404 通常意味着正在运行的 Agent Zero 构建没有内置_a0_connector插件（见 setup-a0-cli/SKILL.md 中的故障排查指引）。

连接选择器（Connection picker）

启动时 A0 CLI 会打开一个宿主机选择器。如果它在当前机器上发现了 Agent Zero，点击Connect；如果 Agent Zero 在其他地方，点击Enter URL manually并粘贴地址。

实用的启动参数：

a0 --host http://localhost:32080 a0 --no-auto-connect a0 --no-docker-discovery

也可以在启动前用环境变量预设地址：

export AGENT_ZERO_HOST=http://localhost:32080 a0

如果启用了Remember this host，CLI 会保存该地址供下次使用。注意：手动输入地址时应使用你当前打开 Agent Zero 的确切 URL 与端口，隧道 URL 按原样粘贴、无需追加端口（见 setup-a0-cli/SKILL.md）。

连接后的 Shell

连接成功后，shell 会显示 Agent Zero 地址、当前项目、模型、本地文件夹、Agent Zero 工作区以及消息输入框。

当终端支持功能键时，可以使用底栏的快捷键：

当 IDE 终端或 SSH 客户端吞掉了功能键时，Ctrl+P是最可靠的替代方案。

F3 / F4 的源码对应关系：这两个快捷键在宿主机侧是权限开关，而在 Agent Zero 侧对应着_a0_connector插件中的两个远程工具：

• F3（文件读写）→ text_editor_remote.py，支持read/write/patch三种动作，把文件编辑操作通过/ws发送到连接的 CLI 机器上执行；
• F4（远程代码执行）→ code_execution_remote.py，支持terminal、python、nodejs、output、reset等 runtime，把 shell 支持的执行操作送到 CLI 机器。

更精确地说，远程文件工具会根据会话元数据判断权限：读取操作只需要文件访问被启用，而write/patch需要写权限，如果没有连接允许写入的 CLI，工具会返回提示 "Press F3 to switch the CLI to Read&Write"（见 text_editor_remote.py）。同理，terminal、python、nodejs、input这类可变运行时要求宿主机侧开启写权限，只有output和reset在只读状态下仍可用（见 code_execution_remote.py）。

斜杠命令

在消息框输入斜杠命令并按回车即可。大部分命令也能从Ctrl+P命令面板中调用。

Host Browser：让 Agent Zero 用你电脑上的浏览器

当页面、登录态或浏览器配置文件应该留在你自己的机器上时，使用 Host Browser 模式让 Agent Zero 通过 A0 CLI 控制你电脑上的浏览器。这对需要真实账号登录、验证码或个性化配置的页面尤其有用。

设置清单

• 保持 A0 CLI 与 Agent Zero 聊天处于连接状态。
• 在 Agent Zero Web UI 中打开 Browser 插件设置，选择Bring Your Own Browser。
• 如果希望 Agent Zero 使用一个已打开的个人浏览器窗口，请先打开该浏览器。
• 在该浏览器中打开其远程调试页面。
• 启用Allow remote debugging for this browser instance。

各浏览器对应的远程调试页面：

当 Agent Zero 对宿主机浏览器执行第一次 Browser 动作时，浏览器会请求确认。若你信任这个 Agent Zero 实例与这条 A0 CLI 连接，点击Allow。

A0 CLI 仅在检查状态时不会接管浏览器，真正的浏览器控制要等到 Agent Zero 实际需要使用浏览器时才启动。

[!IMPORTANT] 远程调试会给已连接的应用对该浏览器会话的完全控制权，包括访问已保存的数据、Cookie、站点数据与导航。只对可信的 Agent Zero 实例、以及你确实打算让 Agent 控制的浏览器窗口使用此功能。

Host browser列表来自已连接的本地 A0 CLI，而不是 Agent Zero Web UI 服务器。它显示 Automatic、当前通告的调试端点以及Custom endpoint。如果新授权的浏览器没有出现，请重启或重连 A0 CLI。

如果勾选检查框在你的浏览器版本上不够用，可以用显式远程调试端口和独立配置文件启动它：

opera --remote-debugging-port=9222 --user-data-dir="$HOME/.config/a0-opera-debug"

然后在 Browser 设置中选择Custom endpoint，或在 A0 CLI 中运行/browser localhost:9222，或把发现地址传给 A0 CLI。完整的 DevTools WebSocket 端点同样可用：

export A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS="http://localhost:9222"

从源码看，宿主浏览器的能力通告由连接器在 WebSocket 握手时上报：ws_connector.py会从connector_hello中读取host_browser元数据并存储（见 ws_connector.py），远程工具状态计算中的host_browser只在"支持且已启用"时为真（见 ws_connector.py）。协议特性列表中还包含browser_host_remote与connector_browser_op（见 ws_connector.py），对应浏览器操作的传输与结果回执。

浏览器配置文件（Browser Profiles）

/browser profile /browser profile chrome Default /browser profile chrome-a0 Default

如果你日常使用的 Chrome 窗口无法被占用，就选择独立的 A0 浏览器配置文件。它有自己的 Cookie 和登录态，所以可能需要在那里登录一次。

选择浏览器模式（Choose Browser Mode）

在 Agent Zero Web UI 中打开 Browser 插件设置，选择以下之一：

• Docker browser：使用 Agent Zero 内置的 Docker 浏览器。
• Bring Your Own Browser：通过 A0 CLI 使用你电脑上的浏览器。如果 A0 CLI 未连接，Agent Zero 会明确告诉你，而不会悄悄改用其他浏览器。

也可以从 CLI 命令面板找到 Browser 命令：

当选择Bring Your Own Browser后，第一次浏览请求会让 A0 CLI 自动准备浏览器。如果你想自己检查或改变状态，这些命令很有用：

/browser status /browser host on /browser relaunch

/browser status显示当前选择的浏览器模式以及浏览器是否就绪：

/browser host把当前聊天切换到 Bring Your Own Browser 模式：

运行/browser container可把该聊天切回 Docker 浏览器模式。

/browser privacy提醒用户浏览器内容策略所在位置：

如果选中的浏览器配置文件已经在另一个窗口打开，请关闭那个窗口再重试，也可以运行/browser relaunch。

无需安装 Chrome DevTools MCP——A0 CLI 已包含连接你批准的浏览器所需的全部组件。

页面隐私（Page Privacy）

Browser 设置决定 Agent Zero 可以如何使用你自己浏览器中的页面文本与截图：

• Local models only：仅在使用本地模型时使用宿主机浏览器的页面内容。
• Warn when using cloud：允许云模型使用，但显示警告。
• Allow：允许且不警告。

[!NOTE] 实时 Browser 面板展示的是 Docker 浏览器。当 Agent Zero 使用你的宿主机浏览器时，结果和截图会出现在聊天中，但实时 Canvas 并不是你个人浏览器窗口的实时流。

源码级原理：连接器如何工作

在仓库中，A0 CLI 的连接能力核心位于_a0_connector插件。连接建立在 Agent Zero 共享的/ws命名空间上，处理器类为WsConnector（见 ws_connector.py）：

• 协议版本与特性协商：PROTOCOL_VERSION = "a0-connector.v1"，WS_FEATURES列表声明了connector_subscribe_context、connector_send_message、text_editor_remote、remote_file_tree、code_execution_remote、computer_use_remote、browser_host_remote、launcher_gateway_control等能力。CLI 发送connector_hello后，服务器回包协议版本、Agent Zero 版本、特性列表与远程工具状态（见 ws_connector.py）。
• 会话认证：requires_auth()返回True，而requires_csrf()返回False、requires_api_key()返回False，说明连接器使用会话认证而非 CSRF 令牌，且不要求 API Key。
• 聊天上下文订阅：CLI 通过connector_subscribe_context订阅某个聊天上下文，可携带history=tail（最近 100 条）或history_before（分页回放）来同步历史，随后进入流式增量推送；connector_send_message则把宿主机输入投递为UserMessage并触发 Agent 运行（见 ws_connector.py）。
• 操作回执机制：文件、执行、Computer Use、浏览器等操作都采用"待决操作 + 回执"模型：Agent 侧工具创建op_id并挂起 future，通过emit_to推送到 CLI（事件如connector_file_op、connector_exec_op），CLI 完成后再以connector_*_op_result回执，由resolve_pending_*_op唤醒 future（见 code_execution_remote.py 与 text_editor_remote.py）。文件结果可能以分块的 JSON/base64connector_file_op_result帧到达，必须收齐同一op_id的所有分块才能解析。
• 执行超时配置：Agent 侧执行超时从_code_execution插件配置读取，默认code_exec_timeouts为(30, 15, 240, 5)秒（first_output / between_output / max_exec / dialog），output_timeouts为(120, 60, 600, 5)秒，等待回执的兜底超时取各超时最大值加 15 秒传输宽限（见 exec_config.py 与 code_execution_remote.py）。
• 远程工具提示词的门控：连接器只在连接了 CLI 时才把远程工具提示词披露给 Agent，且按元数据门控——远程文件元数据启用text_editor_remote，F4 启用的远程执行元数据启用code_execution_remote，受支持的 Computer Use 启用computer_use_remote（见 AGENTS.md）。对应测试覆盖见 tests/test_a0_connector_prompt_gating.py，Launcher 网关回归测试见 tests/test_a0_connector_launcher_gateway.py。
• 会话断连清理：CLI 断开时，服务器会取消流式任务、清除远程文件树快照，并让所有挂起的文件/执行/Computer Use/浏览器/网关控制操作以"CLI 断开"错误失败，防止 Agent 无限等待（见 ws_connector.py）。

把设置交给另一个 Agent

如果另一个 Agent 在协助你完成安装，不要粘贴整份清单，粘贴一行即可：

Set up the A0 CLI connector for Agent Zero on this machine using the setup-a0-cli Skill.

仓库中确实内置了该 Skill（setup-a0-cli/SKILL.md），它引导安装、连接与排查，并强调保持对话简短、只给出下一步。相关的能力边界 Skill 还包括 host-code-execution/SKILL.md（宿主机 shell 执行边界：shell、runtime 与路径都属于 CLI 宿主机，不属于 Agent Zero 服务器或 Docker 容器）以及host-file-editing、host-computer-use等。

故障排除

• 本地看不到任何东西：手动输入 Agent Zero 的 Web 地址，或导出AGENT_ZERO_HOST。
• 你试图从 Docker 内部安装：A0 CLI 属于宿主机，Agent Zero 留在 Docker 中。
• 功能键没有反应：部分终端和 IDE 会捕获功能键，请改用Ctrl+P。
• A0 CLI 提示连接器支持缺失：更新 Agent Zero。
• 宿主机浏览器提示需要修复：运行/browser repair。
• 宿主机浏览器等待重启：关闭所选 Chrome、Edge 或 Chromium 配置文件，再运行/browser relaunch。
• 发现失败：如果自动发现失败，向用户索要确切的 Agent Zero URL，或仅在此时建议使用 Flare Tunnel：Settings > External Services > Flare Tunnel→Create Tunnel→ 把显示的 HTTPS URL 粘贴进a0（见 setup-a0-cli/SKILL.md）。

相关链接

• 快速开始
• 安装指南
• 浏览器指南
• MCP 配置

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero