不写代码搭 AI 智能体：Docker Agent 一个 YAML 跑通，还能接本地模型不用 API Key

本文依据 Docker 官方仓库、官方文档与示例目录整理（核查于 2026-10-08），

一句话： Docker 官方开源的智能体运行工具（Apache-2.0）。把模型、指令、工具写进一个 YAML 文件，一条 docker agent run 就能跑起来；能接云端模型，也能接 Docker Model Runner 跑本地模型，后者不用 API Key、数据不出本机。

痛点：搭个智能体，先写一堆胶水代码

想让大模型帮你读文件、跑命令、查资料，自己拼框架时通常是这个流程：选一家 SDK、写工具的 JSON Schema、写分发逻辑、写对话循环、处理流式输出。换个模型，胶水又要改一遍。做好的智能体想分享给别人，对方还得照着 README 装环境。

Docker Agent 走的是另一条路：配置代替代码。官网的说法很直接——它想做的，是让运行智能体像 docker run 跑容器一样，定义、运行、分发走同一套习惯。

media generation docker agent cover 0 e92bc087 b034 4c70 a16e a30cb1587956

它能解决什么

多智能体协作：一个协调者带几个专长智能体，比如一个写代码、一个做审查，任务自动分发。
工具不用自己造：内置文件系统、Shell、记忆、待办、网页抓取等工具集，还能接任意 MCP 服务器，包括 Docker 的 MCP 目录里的现成服务。
模型随便换：OpenAI、Anthropic、Gemini、AWS Bedrock、Mistral 等云端服务，以及 Docker Model Runner、Ollama 这类本地方案，改一行 model: 就行。
像镜像一样分发：智能体可以推到任意 OCI 仓库，别人拉下来一条命令就能跑，和发 Docker 镜像是同一个心智模型。
多种跑法：交互式终端界面、一次性命令行执行、HTTP API 服务、MCP 服务器模式，同一个 YAML 换个入口就行。

跟之前介绍过的工具正好互补：Agent Reach 解决的是智能体「看不见外面的世界」，Docker Agent 解决的是「智能体本身怎么搭、怎么跑、怎么分享」；它内置的文档检索能力，则和 WeKnora 那种专门的知识库平台形成对照——一个是通用运行框架里带检索，一个是专做知识库。

先看门槛

系统：需要 Docker 环境。Docker Desktop 4.63 及以上版本已经预装了这个插件，装好直接用 docker agent；也可以用 Homebrew 或官方发布的二进制文件单独安装。
模型，二选一：
云端路线：准备至少一家服务商的 API Key，按用量付费；
本地路线：开启 Docker Desktop 的 Model Runner 功能，不用 Key、不用付费，代价是吃本机配置。
硬件（仅本地路线）：没有统一答案，取决于你拉的模型大小。小参数模型对内存要求低、回答质量也有限；想让本地模型稳定地调用工具、读文件、跑多步任务，模型太小很容易翻车。先用官方默认的小模型跑通流程，再按机器配置往上加，这是稳妥顺序。
Windows 用户注意：Docker Desktop 在 Windows 上的容器与 GPU 相关体验，和 WSL 容器是同一套底层语境；本地模型的实际速度、显存占用本文未实测，待验证。

上手：四步

1. 确认插件在不在

docker agent --help
docker agent doctor

第二个命令是官方的体检工具：它会报告各家模型服务的凭据状态、本地 Model Runner 是否可达、已经拉了哪些模型。跑不通先修这里，别急着改 YAML。

2.（本地路线）拉一个模型

docker model status --json
docker model pull ai/qwen3
docker model ls

第一条确认 Model Runner 已开启，后两条拉取并查看本地模型。官方文档提到，没配云端 Key 时，直接运行会优先选已拉到本地的模型。

3. 写你的第一个 YAML

云端路线，最小写法是给模型、说明和指令，再挂上工具集：

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A coding assistant
    instruction: You are an expert developer.
    toolsets:
      - type: filesystem
      - type: shell

本地路线只改模型一行，其余结构不变：

agents:
  root:
    model: dmr/ai/qwen3
    description: A local assistant
    instruction: You are a helpful assistant.
    toolsets:
      - type: filesystem

想接搜索工具，再加一个 MCP 工具集即可，例如官方 README 里用的 DuckDuckGo 容器化 MCP 服务。API Key 只放环境变量，不要写进 YAML——这点官方技能文档也反复强调。

4. 跑起来

docker agent run
docker agent run agent.yaml
docker agent run --exec agent.yaml "帮我看一下这个报错日志"
cat error.log | docker agent run --exec agent.yaml "这段日志哪里出错了"

默认进交互界面；加 --exec 是一次性任务，适合塞进脚本；还有 docker agent new 可以交互式生成一份新配置，不知道从哪下手时先用它打个样。官方示例目录里有上百个现成配置：单智能体、多智能体团队、文档检索、MCP 接入、权限沙箱都有，先抄示例改，比对着空白文件硬写快得多。

常见问题

Q：docker agent 命令不存在？

A：先确认 Docker Desktop 版本够不够新（4.63+ 才预装插件）；单独安装二进制的，要把可执行文件放进 Docker 的插件目录，或者直接用独立命令运行。

Q：本地模型连不上、提示端点为空？

A：按顺序查：Model Runner 功能是否开启、docker model status --json 是否正常、当前 Docker 上下文选的是不是本机引擎。官方排障文档特别提醒，所选连接失败时不会偷偷回退到另一个本地运行器，报错信息里会写明连接名，照着查。

Q：本地小模型不会用工具、答非所问？

A：多半是模型能力问题，不是配置问题。工具调用对模型要求不低，小模型先跑通「只聊天、不挂工具」的配置验证链路，再逐步加工具集；或者把关键智能体切到云端模型，本地模型只做不敏感的子任务。

Q：能不能接我自己的文档做问答？

A：能。内置的检索工具集支持关键词、向量、混合检索和重排几种策略，示例目录里有完整的文档问答配置。但如果你的核心需求就是企业级知识库，还是专门的平台更合适，通用框架里的检索是「够用」定位。

Q：给智能体开 Shell 工具安全吗？

A：这是最需要小心的一项。官方示例里专门有安全模式与沙箱的配置：文件访问可以设允许/拒绝名单，命令也可以放进容器沙箱里跑。原则就一条：只给完成任务必需的最小权限，别图省事把整个磁盘和任意命令都放开。

先泼三盆冷水

更新非常快：仓库已有两百多个发布版本，功能和配置细节变动频繁。本文写法基于 2026-10-08 的官方文档，照抄命令前建议再扫一眼最新文档和示例，别拿旧教程硬套新版。
本地模型是省钱，不是省心：不用 API Key 的代价是效果看机器、看模型。复杂的多智能体协作对小模型并不友好，预期要放低。
YAML 简单，但调试不简单：配置写错、工具权限不对、模型选错，出错表现都差不多。官方提供了单独调试单个工具的命令，排查时先把工具和模型拆开验证，别一上来就跑完整团队。

适合谁 / 不适合谁

适合：已经在用 Docker、想低成本试一把智能体的开发者；想把内部小工具做成智能体分享给同事的人；在意数据隐私、想全程本地跑的人。

不适合：需要深度定制推理逻辑、要把智能体嵌进自家产品核心链路的团队——那还是自己写框架更可控；以及完全不想碰命令行的用户。

一句话

Docker Agent 把「搭智能体」这件事，从写代码变成了填配置：模型、工具、队友都写在 YAML 里，跑法和分发都复用 Docker 的老习惯。它现在迭代极快、坑也不会少，但对已经生活在 Docker 生态里的人，这是目前上手成本最低的智能体玩法之一，值得拿一个下午试试。