尧图网站建设 
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 管规则适配器管状态契约文档明确了三层边界层负责内容不负责SKILL.md通用编排规则host/container 决策、setup 循环、认证人环流程每个 Agent 的具体命令references/agent.md各 Agent 的安装、探测、认证、冒烟、真实任务命令状态检测代码、设置 UI适配器代码helpers/adapters/二进制探测、认证状态检测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 users 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 AgentCodex、Claude Code、Cursor CLI、Gemini CLI、Grok Build、Hermes Agent、OpenCode统一放入同一个 setup 循环决定执行位点用户本机经 A0 CLI还是 Agent Zero 容器 shell用户未指定时先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?用户选择后用memory_save存一条稳定偏好例如 For orchestrator, the user prefers Claude Code to run on the host machine through A0 CLI by default只读对应references/agent.md检查 CLI 是否安装缺失时只安装被请求的那一个 CLI探测--version/--help跑最小冒烟提示词确定性输出TERMINAL_AGENT_SMOKE_OK若冒烟报告缺认证只运行参考文件里点名的 login/setup 命令把 URL、设备码、菜单选项转述给用户等用户确认重试冒烟通过后才运行真实任务。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 CLIreferences/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 Codereferences/claude.mdClaude 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 CLIreferences/cursor.mdCursor 官方二进制叫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_BROWSER1 agent login把打印的 URL 转述给用户确认后重试冒烟。需要结构化输出时换--output-format json轮询进度可用--output-format stream-json --stream-partial-output。Gemini CLIreferences/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-modeyolo --skip-trust # 真实任务 cd $WORKDIR gemini -p $TASK --output-format json --approval-modeyolo --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-modeyolo --skip-trust用户明确只要只读分析时用--approval-modeplan替代yolo。Grok Buildreferences/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 Agentreferences/hermes.mdcommand -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 参数仅在用户或配置提供时追加。OpenCodereferences/opencode.mdcommand -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 Headlessreferences/a0.mda0适配器是唯一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.mdAgentCLI登录方式Agent Zero (headless)a0实例/login会话受保护主机用 shell 中的A0_USERNAME/A0_PASSWORDOpenAI Codexcodex设置界面或外部 CLI 的 ChatGPT 设备登录Claude Codeclaude外部claude登录或ANTHROPIC_API_KEYCursor CLIagentCURSOR_API_KEY、NO_OPEN_BROWSER1 agent login或已缓存的 Cursor 登录Gemini CLIgemini已缓存 Google 登录、GEMINI_API_KEY或 Vertex AI 凭据Grok BuildgrokXAI_API_KEY、grok login --device-auth或已缓存 Grok 登录Hermes Agenthermes外部 Hermes/提供方 setup、~/.hermes/.env、~/.hermes/auth.json或提供方环境变量OpenCodeopencode外部opencode auth login、提供方环境变量或~/.local/share/opencode/auth.json可选命令默认值存放在 plugins/_orchestrator/default_config.yamlSkill 运行时会按需读取/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基类各 Agenta0.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.pyreferences 目录的契约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 的设计可以归纳为三条主线按需加载没有terminal_agent工具委派指令以 Skill 形式存在靠触发词delegate to codex 等在需要时才进入上下文避免常驻提示词膨胀单一 setup 循环 每 Agent 参考文件SKILL.md只维护九步通用循环与七条安全禁令Agent 专属的命令、认证怪癖全部下沉到references/agent.mdSKILL.md保持短小契约明确要求 KeepSKILL.mdshort人环与位点显式化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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero Orchestrator 插件剖析：Skill 契约、双执行位点设计与八大终端编码 Agent 委派实战
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 管规则适配器管状态契约文档明确了三层边界层负责内容不负责SKILL.md通用编排规则host/container 决策、setup 循环、认证人环流程每个 Agent 的具体命令references/agent.md各 Agent 的安装、探测、认证、冒烟、真实任务命令状态检测代码、设置 UI适配器代码helpers/adapters/二进制探测、认证状态检测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 users 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 AgentCodex、Claude Code、Cursor CLI、Gemini CLI、Grok Build、Hermes Agent、OpenCode统一放入同一个 setup 循环决定执行位点用户本机经 A0 CLI还是 Agent Zero 容器 shell用户未指定时先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?用户选择后用memory_save存一条稳定偏好例如 For orchestrator, the user prefers Claude Code to run on the host machine through A0 CLI by default只读对应references/agent.md检查 CLI 是否安装缺失时只安装被请求的那一个 CLI探测--version/--help跑最小冒烟提示词确定性输出TERMINAL_AGENT_SMOKE_OK若冒烟报告缺认证只运行参考文件里点名的 login/setup 命令把 URL、设备码、菜单选项转述给用户等用户确认重试冒烟通过后才运行真实任务。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 CLIreferences/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 Codereferences/claude.mdClaude 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 CLIreferences/cursor.mdCursor 官方二进制叫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_BROWSER1 agent login把打印的 URL 转述给用户确认后重试冒烟。需要结构化输出时换--output-format json轮询进度可用--output-format stream-json --stream-partial-output。Gemini CLIreferences/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-modeyolo --skip-trust # 真实任务 cd $WORKDIR gemini -p $TASK --output-format json --approval-modeyolo --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-modeyolo --skip-trust用户明确只要只读分析时用--approval-modeplan替代yolo。Grok Buildreferences/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 Agentreferences/hermes.mdcommand -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 参数仅在用户或配置提供时追加。OpenCodereferences/opencode.mdcommand -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 Headlessreferences/a0.mda0适配器是唯一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.mdAgentCLI登录方式Agent Zero (headless)a0实例/login会话受保护主机用 shell 中的A0_USERNAME/A0_PASSWORDOpenAI Codexcodex设置界面或外部 CLI 的 ChatGPT 设备登录Claude Codeclaude外部claude登录或ANTHROPIC_API_KEYCursor CLIagentCURSOR_API_KEY、NO_OPEN_BROWSER1 agent login或已缓存的 Cursor 登录Gemini CLIgemini已缓存 Google 登录、GEMINI_API_KEY或 Vertex AI 凭据Grok BuildgrokXAI_API_KEY、grok login --device-auth或已缓存 Grok 登录Hermes Agenthermes外部 Hermes/提供方 setup、~/.hermes/.env、~/.hermes/auth.json或提供方环境变量OpenCodeopencode外部opencode auth login、提供方环境变量或~/.local/share/opencode/auth.json可选命令默认值存放在 plugins/_orchestrator/default_config.yamlSkill 运行时会按需读取/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基类各 Agenta0.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.pyreferences 目录的契约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 的设计可以归纳为三条主线按需加载没有terminal_agent工具委派指令以 Skill 形式存在靠触发词delegate to codex 等在需要时才进入上下文避免常驻提示词膨胀单一 setup 循环 每 Agent 参考文件SKILL.md只维护九步通用循环与七条安全禁令Agent 专属的命令、认证怪癖全部下沉到references/agent.mdSKILL.md保持短小契约明确要求 KeepSKILL.mdshort人环与位点显式化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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考