
Docker Agent cagent 安装教程:5步搭好智能体团队
Docker Agent 是 Docker 开源的多智能体运行时,原项目名 cagent,用一份 YAML 定义整个智能体团队。装到跑通约 5 步:装工具、配密钥、写配置、运行、验证。Docker Desktop 4.63 起自带,工具免费开源,本文含 4 种安装方式、三套 agent.yaml 模板和报错速查表。
想直接抄配置的跳到「3 个可复用 agent.yaml 模板」,装完报错的看「Docker Agent 常见报错速查表」。
Docker Agent 是什么:先分清 cagent 和 Docker Agent
Docker Agent 是 Docker 官方的开源多智能体运行时,让一个 root 智能体当协调者,挂 designer、engineer、qa 等子智能体,各自用不同模型和工具协同干活,而不是让一个通用模型包办。
cagent 是旧名,仓库在 github.com/docker/cagent,官方博客仍常用,命令写作 cagent run;官方文档现统一叫 Docker Agent,命令为 docker agent,配置保留 CAGENT_ 前缀的旧环境变量别名。
别和另一个东西混淆:Docker AI Agent(代号 Gordon)是 Docker Desktop 内嵌的对话助手,负责 Docker 用法问答,不是多智能体运行时。

Docker Agent 安装教程:4 种方式任选
官方提供 4 种安装路径(安装文档),选一种即可。
- Docker Desktop 4.63 及以上自带,直接跑 docker agent version 验证。
- macOS / Linux 用 Homebrew:brew install docker-agent,再跑 docker-agent version。
- GitHub Releases 下载预编译二进制,放 /usr/local/bin,或放 ~/.docker/cli-plugins 注册成 docker 子命令。
- 源码构建:git clone https://github.com/docker/docker-agent.git,装 Go 1.26 和 Task 后执行 task build,产物在 ./bin/docker-agent。
Windows 下载 docker-agent-windows-amd64.exe,改名 docker-agent.exe 放进 PATH 或 ~/.docker/cli-plugins。
装完先 docker agent version 验证。想快速体验直接 docker agent run,进入交互式终端 UI,不需要配置文件。
二进制不放进 ~/.docker/cli-plugins 会出现 docker: 'agent' is not a docker command,解法见报错速查表。国内下载 GitHub 资源可能慢,能不能直连看《Docker Agent 国内能用吗》。
配置模型 API Key:Docker Agent 支持哪些模型
Docker Agent 支持 OpenAI、Anthropic、Google Gemini、Mistral、OpenRouter、GitHub Copilot 等,也能通过 Docker Model Runner 跑本地模型,本地模型不需要 API Key。
密钥用环境变量注入,官方要求不写进配置文件:OPENAI_API_KEY 对应 OpenAI,ANTHROPIC_API_KEY 对应 Anthropic,GOOGLE_API_KEY 或 GEMINI_API_KEY 对应 Google Gemini,GITHUB_TOKEN 对应 GitHub Copilot。
设置方式:export 到 shell;或 docker agent setup 把密钥存进 ~/.config/cagent/.env 自动读取。想离线用 docker model pull ai/qwen3 拉本地模型,再 docker agent run --model dmr/ai/qwen3 跑。额度细节看《Docker Agent 免费额度指南》。
编写 agent.yaml:多智能体团队配置
Docker Agent 用 YAML 描述整个团队,默认文件名 agent.yaml(旧文档也叫 cagent.yaml)。version 是配置版本号,官方当前推荐 15;models 定义模型;agents 定义智能体,至少一个。
智能体有五个核心属性:model 指定模型,description 说明职责,instruction 写指令,sub_agents 声明可委派对象,toolsets 声明工具。内置工具含 filesystem(读写文件)、shell(跑命令)、think(推理)、todo、memory(持久记忆)、mcp。
最小配置:
agents:
root:
model: anthropic/claude-sonnet-4-5
description: 一个乐于助人的编码助手
instruction: |
你是资深软件工程师,帮用户写干净高效的代码。
toolsets:
- type: filesystem
- type: shell
- type: think
组团队就在 root 下挂 sub_agents。五个属性细节看《Docker Agent YAML 配置教程》。

运行与验证:docker agent run 系列命令
写好后 docker agent run agent.yaml 进入交互式终端 UI。常用变体:docker agent run 跑默认智能体;docker agent new 向导生成配置,可加 --model openai/gpt-5;docker agent run myorg/agent:tag 跑 OCI 仓库分享的智能体;docker agent run --exec agent.yaml "任务" 做一次性任务;加 --yolo 自动批准工具调用。官方快速开始见这里。
跑不通先 docker agent doctor,一次性检查密钥、Model Runner、auto 模型选择,并给出下一步。这是官方推荐的排错第一步。

3 个可复用 agent.yaml 模板
模板一:最小单智能体,快速验证安装和密钥。
version: 15
agents:
root:
model: openai/gpt-5
description: 一个乐于助人的助手
instruction: 你是一个乐于助人的助手。
toolsets:
- type: think
模板二:多智能体团队,root 协调、engineer 实现、qa 测试。
version: 15
models:
sonnet:
provider: anthropic
model: claude-sonnet-4-5
agents:
root:
model: sonnet
description: 产品经理,负责拆需求和协调团队
instruction: |
把需求拆成小迭代,协调 engineer 和 qa 完成任务。
sub_agents: [engineer, qa]
toolsets:
- type: filesystem
- type: think
- type: todo
engineer:
model: sonnet
description: 工程师,负责实现功能
instruction: |
按设计实现功能,写干净、可测试的代码。
toolsets:
- type: filesystem
- type: shell
- type: think
qa:
model: sonnet
description: 测试工程师,负责测试和找 Bug
instruction: |
测试功能并找出 Bug,把问题报告给 root。
toolsets:
- type: filesystem
- type: think
模板三:带记忆和 MCP 工具。
version: 15
agents:
root:
model: anthropic/claude-sonnet-4-5
description: 带持久记忆的研究助手
instruction: |
联网搜索信息,记住重要发现,输出分析结论。
toolsets:
- type: think
- type: memory
path: ./research.db
- type: mcp
ref: docker:duckduckgo
模板三里的 ref: docker:duckduckgo 把 MCP 服务器跑在 Docker 容器里,是官方推荐的安全接法,需要 Docker Desktop 在运行。memory 给智能体挂本地 SQLite 记忆库,跨会话记住上下文。
Docker Agent 常见报错速查表
| 错误现象 | 原因 | 解法 |
|---|---|---|
| docker: 'agent' is not a docker command | 未安装,或二进制没注册成 CLI 插件 | 把 docker-agent 放进 ~/.docker/cli-plugins,或升级到 Docker Desktop 4.63+ |
| The following environment variables must be set | 模型商密钥没配 | export 对应变量,或 docker agent setup 写入 ~/.config/cagent/.env |
| No model is currently available | auto 选不出可用模型 | docker model pull ai/qwen3 拉本地模型,或配任一云端密钥 |
| model xxx is not pulled in Docker Model Runner | 本地模型没拉取 | 先 docker model pull ai/qwen3,用 docker model ls 查已有模型 |
| context_length_exceeded | 上下文超限 | 会话里 /compact 压缩历史,或调小 num_history_items |
| Max iterations reached | 达到迭代上限 | 调大 max_iterations,开 --debug 看是否死循环 |
| HTTP 429 | 被模型商限流 | 配 fallback 模型和 cooldown,日志会显示 Switching to fallback model |
| YAML 解析报错(带行号) | 缩进或引号问题 | YAML 对空白敏感,别用 tab,特殊字符加引号 |
| 模型名报错 | 模型名写错或大小写不符 | openai/gpt-5 和 openai/GPT-5 不是同一个,核对官方名称 |
想给编辑器加实时校验,官方提供 JSON Schema:https://github.com/docker/docker-agent/blob/main/agent-schema.json,写配置自动补全。
常见问题
Docker Agent 和 cagent 是什么关系?
答:同一个项目。cagent 是旧名,官方博客仍写作 cagent run;文档现统一叫 Docker Agent,命令为 docker agent,CAGENT_ 前缀环境变量仍兼容。
Docker Agent 安装必须装 Docker Desktop 吗?
答:不是必须。Homebrew、GitHub Release 二进制、源码构建都能独立安装。Docker Desktop 只在想用容器跑 MCP 工具或本地模型时才需要。
Docker Agent 是免费的吗?
答:工具本身开源免费,Docker Desktop 个人版也是 0 元。花钱的只有模型 API 调用费,跑本地模型可以不花钱,额度细节见《[Docker Agent 免费额度指南](/ai-guide/docker-agent-free-guide)》。
cagent.yaml 和 agent.yaml 有什么区别?
答:没有本质区别。cagent.yaml 是旧文档的默认文件名,官方文档现在用 agent.yaml,两种都能被 docker agent run 识别。
Docker Agent 怎么跑多智能体团队?
答:在 agents 段定义多个智能体,root 用 sub_agents 声明可委派对象,docker agent run agent.yaml 后由 root 分派任务。单智能体与多智能体的取舍见《[Docker Agent vs Claude Code 对比](/ai-guide/docker-agent-vs-claude-code)》。
Docker Agent 和 Docker AI Agent(Gordon)是同一个吗?
答:不是。Gordon 是 Docker Desktop 内嵌的对话助手,负责 Docker 用法问答;Docker Agent(cagent)是独立开源的智能体运行时,编排多智能体团队。

京ICP备2024094994号-29