企业官网建设流程全解析

Agent Zero Orchestrator 插件剖析：Skill 契约、双执行位点设计与八大终端编码 Agent 委派实战

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

本文围绕 Agent Zero_orchestrator插件中的orchestratorSkill 展开，完整解析其 Skill 契约（front matter 工具白名单、references/分层职责、宿主/容器双流程规则），并逐一走通 Codex、Claude Code、Cursor CLI、Gemini CLI、Grok Build、Hermes、OpenCode 与 A0 Headless 的安装探测、冒烟测试、认证与真实任务命令，最终结合插件源码说明适配器注册与状态检测的落地方式。读完本文，你既能把外部终端编码 Agent 安全地接入 Agent Zero，也能理解"按需加载的重委派指令"这一插件架构的设计动机。

一、orchestrator Skill 的定位与职责边界

Agent Zero 是一个运行在 Docker 容器内的 AI Agent 框架。它自身可以执行代码，但许多开发者更希望把编码任务委派给终端上的专业编码 Agent（如 Claude Code、Codex CLI 等）。_orchestrator插件为此提供三块能力：

• 一个orchestratorskill：告诉 Agent Zero 如何通过用户宿主机上的 A0 CLI 桥或容器内普通 shell 驱动外部 CLI；
• 一个Settings > External Services 状态界面：展示已注册二进制、安装状态与检测到的认证来源；
• 一组适配器元数据：覆盖 Agent Zero headless、OpenAI Codex CLI、Claude Code、Cursor CLI、Gemini CLI、Grok Build、Hermes Agent、OpenCode。

插件刻意不提供terminal_agent工具，也不在设置界面提供安装按钮。核心动机写在插件 README 中：把庞大的委派指令做成按需加载的 Skill，而不是常驻每个 Agent 的系统提示词里。只有当用户明确要求"委派给某个终端编码 Agent"时，才通过 Skill 触发词加载这些重型指令，从而控制提示词预算。

orchestrator Skill 的契约文档即 skills/orchestrator/AGENTS.md，它用"目的 / 所有权 / 本地契约 / 工作指引 / 验证"五段式约束了 Skill 的维护规则。

所有权划分：Skill 管规则，适配器管状态

契约文档明确了三层边界：

契约还规定：状态检测、UI 状态、安装 API 不属于本 Skill 的所有权范围——这些由插件的 Python 适配器承担（见 plugins/_orchestrator/helpers/adapters/）。

二、front matter：工具白名单与触发词

Skill 的元数据定义在 skills/orchestrator/SKILL.md 的 front matter 中，契约要求这里必须放行四个工具：

name: orchestrator description: Use when delegating coding or repository work to external terminal coding agents such as the user's host Claude Code/Codex/Cursor/Gemini CLI or container-installed pal agents. triggers: - "terminal agent" - "external coding agent" - "delegate to codex" - "delegate to claude code" - "delegate to cursor" - "delegate to cursor cli" - "delegate to gemini cli" - "delegate to grok build" - "delegate to a0 headless" - "delegate to hermes" - "delegate to opencode" allowed_tools: - code_execution_tool - code_execution_remote - memory_load - memory_save

四个工具各司其职：

• code_execution_tool：在 Agent Zero 容器内执行命令，对应"容器内 pal agent"流程；
• code_execution_remote：通过 A0 CLI 连接在用户宿主机执行命令，对应"宿主 CLI"流程；
• memory_load/memory_save：记忆每个 Agent 的执行位点偏好（host 还是 container），避免每次委派都重复询问。

值得注意的是 SKILL.md 正文第一条规则即强调：不存在terminal_agent工具。这是契约对正文的硬性要求——防止 Agent 虚构调用一个不存在的工具。委派实际通过 shell / 代码执行完成，Skill 只是让"重型委派指令"在需要时才载入上下文。

三、双执行位点：Host CLI 流程与容器 Pal 流程

orchestrator 的核心决策点是：命令到底在哪里跑？SKILL.md 把支持委派的所有非 A0 Agent（Codex、Claude Code、Cursor CLI、Gemini CLI、Grok Build、Hermes Agent、OpenCode）统一放入同一个 setup 循环：

1. 决定执行位点：用户本机（经 A0 CLI）还是 Agent Zero 容器 shell；
2. 用户未指定时，先memory_load查该 Agent 的历史偏好；仍未知则直接询问："Do you want me to use your own local <agent> through A0 CLI, or the <agent> installed inside the Agent Zero container?"；
3. 用户选择后，用memory_save存一条稳定偏好，例如 "For orchestrator, the user prefers Claude Code to run on the host machine through A0 CLI by default"；
4. 只读对应references/<agent>.md；
5. 检查 CLI 是否安装，缺失时只安装被请求的那一个 CLI；
6. 探测--version/--help；
7. 跑最小冒烟提示词（确定性输出TERMINAL_AGENT_SMOKE_OK）；
8. 若冒烟报告缺认证，只运行参考文件里点名的 login/setup 命令，把 URL、设备码、菜单选项转述给用户，等用户确认；
9. 重试冒烟通过后，才运行真实任务。

Host CLI 流程（用户本机）

当用户想用自己电脑上的 Claude Code / Codex 等 CLI 时：

• 必须用code_execution_remote而非code_execution_tool，因为路径、shell、登录态和已装 CLI 都属于 A0 CLI 宿主机；
• 若code_execution_remote不可用（未连接 CLI 或远程执行被禁用），Skill 会输出一段固定引导文案，让用户在本地安装 A0 CLI：

# macOS / Linux curl -LsSf https://cli.agent-zero.ai/install.sh | sh # Windows PowerShell irm https://cli.agent-zero.ai/install.ps1 | iex

若 A0 CLI 已装未运行，执行a0并连接本实例；远程/VPS 实例需手动填 Agent Zero URL。在 A0 CLI 中按F4允许 Remote Code Execution，任务需要写宿主文件时再按F3。此后"使用本地 <agent>"的请求就会落在宿主机上执行。

• 工作目录语义保持在宿主侧：cd到宿主项目路径，而不是容器的/a0/usr/workdir；
• 可选加载host-code-executionSkill 获取宿主 shell 安全规则。

容器 Pal 流程（Docker 内）

当用户明确要容器内运行时：

• Agent Zero Headless 是特例：读 references/a0.md，走目标实例选择流程，而不是非 A0 的 setup 循环；
• 其余 Agent 严格走"读参考文件 → 检查安装 → 缺失则只装这一个 → 探测 → 冒烟 → 认证人环 → 重试 → 真实任务"的九步循环；
• 允许在同一个工作流里同时咨询宿主和容器两个 Agent，但 shell 会话必须分开，标注每个答案来自哪个 Agent/位点，比较结果后再行动。

安全边界（契约中的硬性禁令）

契约和 SKILL.md 共同划定了几条不可逾越的边界：

• 禁止用 Computer Use 驱动编码 Agent 的终端/TUI/菜单——只走 headless CLI 命令，走不通就停下来问；
• 认证必须人环：可以发起 CLI 登录命令、转述精确的 URL/设备码/浏览器步骤，但必须等用户确认完成后再重试冒烟；
• 禁止把裸 CLI 当登录兜底：若不慎打开了全屏 TUI（看到 welcome、theme、provider 菜单），要重置终端会话，而不是往里面按 Enter 或发/login；
• 登录菜单选项要在聊天中转述并让用户选，再把用户选的编号/按键发回终端会话；
• 绝不要求用户往聊天里贴密钥，优先浏览器/设备码登录、CLI 自身提示或聊天外设置的环境变量；
• 长任务保持在一个 shell 会话里轮询输出，不要给终端 Agent 再包一层自己的超时；
• 任务简报必须自包含：目标、目标文件或仓库路径、约束、验证命令、期望输出；
• 终端 Agent 结束后必须自己检查产出、验证关键改动，再汇报成功；
• ACP 只作为社区插件可选路径提及，默认不假设已安装。

四、八大 Agent 参考手册：安装、冒烟与真实任务命令

契约规定"Agent 专属的命令、认证怪癖、安装提示、冒烟提示词都放在对应的references/<agent>.md"，且SKILL.md必须要求 Agent 行动前只读相关的那一份。以下是各参考文件的要点（文件均位于 plugins/_orchestrator/skills/orchestrator/references/）。

Codex CLI（references/codex.md）

容器内 Codex 自带沙箱可能失败，因此 Docker 安全默认值直接绕过审批与沙箱：

# 安装与探测 command -v codex >/dev/null || npm install -g @openai/codex codex --version # 冒烟 cd "$WORKDIR" codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "Respond exactly: TERMINAL_AGENT_SMOKE_OK" # 真实任务 cd "$WORKDIR" codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "$TASK"

若设置界面曾以插件自有 device-code 登录连接 Codex，需先export CODEX_HOME=/a0/usr/plugins/_orchestrator/data/codex；若运行时支持 Codex 自己的沙箱，可省略 bypass 参数；有模型覆盖时加-m "$MODEL"。

Claude Code（references/claude.md）

Claude Code 用 print 模式，且"跳过权限"（bypassPermissions）仅在非 root shell下才是默认非交互模式——root 下会被拒绝。这正是契约中"Root shells must not use Claude CodebypassPermissions"一条的落地：

# 安装与探测 command -v claude >/dev/null || npm install -g @anthropic-ai/claude-code claude --version claude auth status || true # 冒烟（按是否 root 分支） cd "$WORKDIR" if [ "$(id -u)" -eq 0 ]; then claude -p "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --output-format json else claude -p "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --output-format json --permission-mode bypassPermissions --allowedTools Bash,Read,Edit fi

认证部分是该参考文件的重点，契约有两条专门约束：

• 在用户明确选择--claudeai、--console、--sso或外部 API key 之前，不要运行裸claude或裸claude auth login（裸claude会打开首跑 TUI，把 Agent 困在主题/provider 菜单里）；
• 使用 API key 认证时，密钥必须取自 Agent Zero 的 secrets 文件/a0/usr/.env，而不是 workdir 下的.env。

参考文件给出的密钥加载模板（部分 Agent Zero 安装把密钥存成API_KEY_ANTHROPIC，需映射为 CLI 变量）：

set -a . /a0/usr/.env set +a [ -z "${ANTHROPIC_API_KEY:-}" ] && [ -n "${API_KEY_ANTHROPIC:-}" ] && export ANTHROPIC_API_KEY="$API_KEY_ANTHROPIC"

若之前的尝试已经把裸claudeTUI 打开且终端里只有菜单，正确动作是重置终端会话，然后在干净会话里跑对应认证命令。

Cursor CLI（references/cursor.md）

Cursor 官方二进制叫agent，不带-p会进交互 TUI：

# 安装与探测 command -v agent >/dev/null || curl https://cursor.com/install -fsS | bash agent --version agent status || true # 冒烟 cd "$WORKDIR" agent -p --output-format text "Respond exactly: TERMINAL_AGENT_SMOKE_OK" # 真实任务 cd "$WORKDIR" agent -p --force --output-format text "$TASK"

认证优先CURSOR_API_KEY；同样支持从/a0/usr/.env加载并把API_KEY_CURSOR映射为CURSOR_API_KEY的模板。容器/远程环境里的浏览器登录用NO_OPEN_BROWSER=1 agent login，把打印的 URL 转述给用户，确认后重试冒烟。需要结构化输出时换--output-format json，轮询进度可用--output-format stream-json --stream-partial-output。

Gemini CLI（references/gemini.md）

裸gemini会开 TUI，必须传-p。安装命令必须单独成条并在同一终端会话里等待/轮询完成，不能把 version/help/冒烟追加到安装命令后面：

npm install -g @google/gemini-cli --no-progress # 安装（独立会话轮询） # 冒烟 cd "$WORKDIR" gemini -p "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --output-format json --approval-mode=yolo --skip-trust # 真实任务 cd "$WORKDIR" gemini -p "$TASK" --output-format json --approval-mode=yolo --skip-trust

认证支持缓存的 Google 登录、GEMINI_API_KEY、Vertex AI 凭据三类。契约对这条路径有一条专门约定：当GEMINI_API_KEY已在 Agent Zero secrets 中登记时，容器内应使用§§secret(GEMINI_API_KEY)语法而不是假设它已从/a0/usr/.env导出：

GEMINI_API_KEY='§§secret(GEMINI_API_KEY)' gemini -p "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --output-format json --approval-mode=yolo --skip-trust

用户明确只要只读分析时，用--approval-mode=plan替代yolo。

Grok Build（references/grok.md）

# 安装（脚本被墙时改用 npm 官方发行版） command -v grok >/dev/null || curl -fsSL https://x.ai/cli/install.sh | bash npm install -g @xai-official/grok # 备选 # 冒烟与真实任务（形态相同，替换提示词） grok --no-auto-update --cwd "$WORKDIR" -p "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --output-format json --always-approve --no-alt-screen

认证优先XAI_API_KEY，同样提供API_KEY_XAI到XAI_API_KEY的/a0/usr/.env映射模板；账号登录走grok login --device-auth并把 URL 与 user code 转述给用户。会话续接（--session-id/--resume/--continue）仅在用户明确要求时使用。

Hermes Agent（references/hermes.md）

command -v hermes >/dev/null || curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes --version || hermes --help # 冒烟 cd "$WORKDIR" hermes chat --quiet --source tool -q "Respond exactly: TERMINAL_AGENT_SMOKE_OK" --yolo

需要 setup 时跑hermes setup --portal，转述 OAuth/浏览器步骤，等确认后重试冒烟；真实任务把提示词换成$TASK，模型/提供方/toolsets 参数仅在用户或配置提供时追加。

OpenCode（references/opencode.md）

command -v opencode >/dev/null || curl -fsSL https://opencode.ai/install | bash opencode --version || opencode --help # 冒烟 opencode run --dir "$WORKDIR" --auto "Respond exactly: TERMINAL_AGENT_SMOKE_OK"

认证走opencode auth login（不可用时回退opencode+/connect），保持人环边界；真实任务替换$TASK即可。

Agent Zero Headless（references/a0.md）

a0适配器是唯一"setup 例外"：不走通用登录流程。用户没指定目标实例时要问"用本实例还是另起一个实例"，避免递归委派（要明确告诉目标实例直接回答、不要再经终端 Agent 转派）。

# 探测 command -v a0 >/dev/null || test -x /opt/venv/bin/a0 # 新会话（容器内默认指向本地实例 http://localhost:80） cd "$WORKDIR" a0 headless --host http://localhost:80 --no-docker-discovery --output jsonl --new-chat --workspace "$WORKDIR" -p "$TASK" # 续会话 a0 headless --host "$A0_HOST" --no-docker-discovery --output jsonl --chat "$CONTEXT_ID" --workspace "$WORKDIR" -p "$TASK"

受保护的远端主机用 CLI 支持的环境变量（如A0_USERNAME/A0_PASSWORD），不要自造用户名/密码 flag。

五、支持的 Agent 一览与插件配置

插件 README 汇总的 Agent/CLI/登录方式对照表如下（源自 plugins/_orchestrator/README.md）：

可选命令默认值存放在 plugins/_orchestrator/default_config.yaml，Skill 运行时会按需读取/a0/usr/plugins/_orchestrator/config.json中对应适配器的配置块，且绝不打印密钥。默认配置覆盖每个适配器的binary、可选model与各家特性开关：

a0: binary: a0 # Agent Zero Docker 内回退到 /opt/venv/bin/a0 host: "" # 空 = 取 AGENT_ZERO_HOST 环境变量，否则本地实例 codex: binary: codex model: "" bypass_sandbox: true claude: binary: claude model: "" permission_mode: bypassPermissions allowed_tools: "Bash,Read,Edit" bare: false cursor: binary: agent output_format: text force: true gemini: binary: gemini model: "" grok: binary: grok model: "" output_format: json always_approve: true no_auto_update: true hermes: binary: hermes model: "" provider: "" toolsets: "" yolo: true opencode: binary: opencode model: "" agent: "" auto: true

六、源码纵深：适配器注册、状态检测与验证方式

适配器与注册表

插件的 Python 侧位于 plugins/_orchestrator/helpers/。从源码结构看：

• helpers/adapters/base.py定义TerminalAgentAdapter基类，各 Agent（a0.py、codex.py、claude.py、cursor.py、gemini.py、grok.py、hermes.py、opencode.py）各自实现安装探测与auth_status()；
• helpers/registry.py注册所有适配器实例，状态 API 与设置 UI 会自动拾取已注册适配器，无需单独接线；
• api/status.py对外暴露状态查询，api/start_device_login.py/api/poll_device_login.py支持 Codex 的插件自有设备码登录，api/disconnect.py仅在适配器能安全移除已知凭据存储时才允许断开凭据。

插件 README 给出的"新增一个 Agent"五步流程与契约中"references 文件名尽量与 adapter id 一致"相互印证：新建helpers/adapters/<name>.py（实现auth_status()）→ 在helpers/registry.py注册 → 在default_config.yaml加配置块 → 写skills/orchestrator/references/<name>.md→ 更新SKILL.md的参考索引与 README 步骤。

凭据安全

Codex 插件自有登录的 token 存放在插件数据目录data/codex/auth.json（权限 600）。README 特别强调：token 与密码等价，不要让两个客户端轮转共享同一个 refresh-token 凭据文件，插件自有的 Codex 凭据要与其他工具隔离。

验证命令

契约给出的验证方式是直接运行适配器测试（容器 ID 需按实际环境替换）：

docker exec 8dc967046cda bash -lc 'cd /a0 && /opt/venv-a0/bin/python plugins/_orchestrator/tests/test_status_adapters.py'

对应的测试文件即 plugins/_orchestrator/tests/test_status_adapters.py，references 目录的契约（references/AGENTS.md）也指向同一条验证命令，说明 Skill 文档与适配器代码共享同一套回归验证。

七、参考文件目录的维护契约

references/AGENTS.md 对每份 Agent 手册提出统一要求：

• 每份参考必须包含：何时用该 Agent、安装/探测命令、认证/setup 行为、冒烟命令、真实任务命令形态；
• 通用规则（裸 CLI 兜底禁令、聊天不贴密钥、显式 workdir、冒烟先于真实任务）留在父级SKILL.md，不下沉到各参考文件；
• 参考文件保持"可整块复制"的操作性：命令放进 fenced bash 块，密钥一律用环境变量或 Agent Zero secret 路径引用且不打印值；
• 新增参考文件时，必须同步更新父级SKILL.md的参考索引、README 的加 Agent 步骤和测试。

八、总结：一个"提示词经济学"驱动的委派框架

回看整份契约，orchestrator Skill 的设计可以归纳为三条主线：

1. 按需加载：没有terminal_agent工具，委派指令以 Skill 形式存在，靠触发词（"delegate to codex" 等）在需要时才进入上下文，避免常驻提示词膨胀；
2. 单一 setup 循环 + 每 Agent 参考文件：SKILL.md只维护九步通用循环与七条安全禁令，Agent 专属的命令、认证怪癖全部下沉到references/<agent>.md，SKILL.md保持短小（契约明确要求 "KeepSKILL.mdshort"）；
3. 人环与位点显式化：host/container 选择显式询问并持久化到 memory，认证步骤永远由用户确认闭环，密钥只从/a0/usr/.env或§§secret(...)注入，聊天中不落密钥。

对于想把 Claude Code、Codex、Cursor、Gemini、Grok、Hermes、OpenCode 甚至另一个 Agent Zero 实例纳入统一工作流的开发者，这套 Skill + 适配器 + 状态 UI 的三层结构，以及它可复现的安装/冒烟/认证/真实任务命令链，是可以直接参照落地的模板。

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