docker-agent-run

Docker Agent：运行和操作 Agent

概述

本技能负责 Docker Agent 的运行操作：针对本地配置、别名或注册表引用调用 docker agent run；选择 Agent 对工具调用的自主程度；将其隔离在沙盒 VM 中；以及诊断运行失败的原因。本技能假设 agent.yaml 已经存在——编写该文件请参阅“相关技能”。

何时使用此技能

在以下情况下启用此技能：

• 用户想要交互式运行 Agent，或以无头模式运行（--exec）。
• 用户正在选择或调试工具调用的 --safety、--yolo 或审批行为。
• 用户想用 --sandbox 隔离 Agent 对 Shell／文件系统的访问，或遇到了沙盒网络策略错误。
• 用户想要可复用的快捷方式（docker agent alias）、限定范围的 Git 工作树（--worktree），或正在调试凭据／模型可用性（docker agent doctor）。

何时不要使用此技能

在以下情况下不要使用此技能：

• 任务使用独立的 sbx run/create/stop/rm，而不是 docker agent run --sandbox——请使用 docker-sandboxes-lifecycle。
• 任务是配置独立的 sbx policy 或 sbx secret——请使用 docker-sandboxes-network-credentials。如果用户只提到“我的沙盒”，请先确认使用的是哪个 CLI，再推荐命令。
• 任务是编写或编辑 agent.yaml 本身（模型、工具集、sub_agents）——请使用 docker-agent-config。
• 任务是将 Agent 暴露为服务（serve）、通过注册表共享（share），或对其进行评估（评估会话、--baseline 回归门槛）——请使用 docker-agent-deploy。

核心指南

安全模式

• docker agent run 支持四种 --safety 模式；请选择能让任务完成的最低权限模式：
  • strict — 每次工具调用前都请求审批。
  • balanced — 自动批准被归类为安全的调用，其余调用则请求审批。
  • restricted — 自动批准安全调用，其余调用一律拒绝。适用于无人能响应提示词的无人值守／CI 运行。
  • autonomous — 自动批准所有调用。等同于 --yolo。
• 无人值守运行（定时任务、CI、服务端点）绝不要默认使用 autonomous／--yolo。无人值守运行请使用 restricted，这样意外的工具调用会以拒绝方式失败，而不会未经审核就执行；autonomous／--yolo 仅适用于处于沙盒中的或完全可信的交互式会话。

  # CI-safe: unreviewed tool calls are denied, not silently approved.
  docker agent run --exec --safety restricted ./agent.yaml "Triage the failing test"
  

• 在别名中设置安全默认值，避免调用方忘记设置；并说明在 docker agent run 中显式指定 CLI --safety／--yolo 仍会覆盖该别名：

  docker agent alias add safe-coder myorg/coder --safety balanced
  

沙盒隔离

• --sandbox 会在由 sbx CLI 管理的隔离微型 VM 中运行 Agent（这是另一项前置要求——请先安装并配置）。内置工具集启动的所有 Shell、文件系统和进程活动都在 VM 内进行；挂载的只有工作目录（以及未指定 --no-kit 时暂存的一套技能／提示词文件“套件”）。**例外：**Agent 中声明的本地 stdio MCP 服务会作为主机进程在沙盒 VM 之外运行——请将这类 MCP 服务视为可信的主机集成，而非沙盒内运行的服务。

  docker agent run --sandbox ./agent.yaml
  

• 沙盒网络代理采用默认拒绝策略：仅开放模型提供方、 models.dev，以及工具集解析器能够推断出的主机。自定义 MCP 服务或第三方 API 通常需要显式添加到允许列表——请将其永久添加，避免每次运行时都重新查找：

  docker agent sandbox allow api.example.com
  docker agent sandbox list
  docker agent sandbox deny api.example.com
  

• 优先在 Agent 自身的 agent.yaml 中设置 runtime: {sandbox: true}，而不是每次调用该 Agent 时都记得加上 --sandbox；在 CLI 中显式指定 --sandbox=false 仍可在单次调试运行时覆盖配置默认值。
• 沙盒会持续存在，并在同一工作区的后续运行中复用——会话结束时不会销毁。不要期望每次运行都会获得干净的 VM；如果需要，请更改挂载集合（例如使用新的套件）以强制重新创建。

别名和默认 Agent

• 注册一次快捷方式，然后按名称而非路径运行：

  docker agent alias add code myorg/notion-expert
  docker agent run code
  

• 在本地运行且未指定 Agent 参数时，docker agent run 会依次在当前目录查找 docker-agent.yaml、docker-agent.yml 和 docker-agent.hcl（以第一个匹配项为准）。只有在这些文件都不存在时，才会解析 default 别名；若该别名也不存在，则回退到内置默认 Agent。 这些技能中的 agent.yaml 示例会显式传入文件名； agent.yaml 不是自动发现时使用的文件名。
• 使用 default 别名设置没有项目配置的目录所用的回退选项。即使存在项目配置，也可以显式传入 default 来选择它：

  docker agent alias add default ./my-agent.yaml
  docker agent run default
  

• docker agent run <alias> 上的 CLI 标志始终会覆盖别名自身存储的选项（例如，docker agent run yolo-coder --yolo=false）。

Worktree

• 使用 --worktree（-w）将 Agent 对文件的修改与当前 检出分离——它会在全新的 git worktree 中运行 Agent。对于 交互式会话，干净的 worktree（没有未提交的更改、 未跟踪的文件或新提交）会在会话结束时自动移除；如果有更改，则会提示你保留或移除。无头 运行（--exec）无论状态如何都不会自动清理 worktree——它会保留在原处供检查：

  docker agent run ./agent.yaml --worktree=auth-refactor --worktree-base origin/main
  

• --worktree 不能与 --remote 或 --sandbox 同时使用。若要恢复 worktree 运行，请传入 --session -1（或会话 ID）——不要再次传入 --worktree，因为 worktree 已存在，会导致失败。

故障排查

• “No model is currently available”或“model ... is not pulled”表示 Agent 的提供方没有可用凭据，或者（对于 dmr/）模型 尚未拉取。修改 YAML 前，先运行 docker agent doctor ./agent.yaml——它会 报告解析后的模型/提供方以及是否找到了凭据。如果缺少凭据，请导出提供方的 API 密钥；如果缺少 DMR 模型，请运行 docker model pull <model>。重试任务前，再次运行 doctor。
• 如果 Agent 只描述计划而不执行，通常是缺少所需的工具（在 agent.yaml 中添加 type: shell 或 type: todo），而不是模型故障——请将此情况交由 docker-agent-config 处理。
• 沙盒运行中出现 403 Blocked by network policy 错误，表示 目标未列入允许列表；请使用 docker agent sandbox allow <host>。

相关技能

• 单独使用 sbx 生命周期命令，请使用 docker-sandboxes-lifecycle。
• 单独使用 sbx policy 和 sbx secret，请使用 docker-sandboxes-network-credentials。
• 编写或修改底层 agent.yaml（模型、工具集、sub_agents），请使用 docker-agent-config。
• 部署、共享或评估 Agent，请使用 docker-agent-deploy。

参考资料

• references/safety-and-sandbox.md — 完整的安全模式/标志交互表和沙盒信任边界详情。
• references/sources.md — 本技能中每条规则的来源。

资源

• 无。

检查

• checks/verification.md — docker agent run 调用的验证操作指南。