
Docker Agent API Key 配置:4 种方式与验证
Docker Agent API Key 配置的核心是选对存放位置。官方给了四种方式:环境变量、env 文件、Docker Compose secrets,以及 Sandboxes 的凭据代理。选错了会出现「配了但读不到」或「读到了但沙箱里是占位符」。

先分清两套配置体系
Docker Agent 有两条运行路径,凭据机制完全不同。
一条是直接用本体,docker agent run agent.yaml。它按六层优先级链找 key,从高到低依次是环境变量、Compose secrets、Docker Agent env 文件、ChatGPT 登录、凭据助手、Docker Desktop 后端,第一个有值的生效。
另一条是在 Docker Sandboxes 里跑 sbx run docker-agent。沙箱内代理会拦截出站请求,真实凭据留在宿主机,沙箱里永远只有 proxy-managed 占位符。
两条路径不能混用。在沙箱里 export key 没用,官方还提醒过别在沙箱里把 key 设成无效值,那会打乱代理注入。

方式一:环境变量,本地开发最快
最直接的做法,官方示例:
export ANTHROPIC_API_KEY=<your_key> # Claude 模型
export OPENAI_API_KEY=<your_key> # OpenAI 模型
export GOOGLE_API_KEY=<your_key> # Gemini 模型
然后 docker agent run debugger.yaml 就能跑。内置厂商变量名官方列了完整表,常用的:OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY 或 GEMINI_API_KEY、DEEPSEEK_API_KEY、OPENROUTER_API_KEY。Anthropic 和 Google 还支持用 token_key 改成自定义变量名,适合一个 shell 里放多个不同账号。
环境变量排第一,适合临时切换账号,缺点是会进 shell 历史和进程列表,别放长期凭据。
方式二:env 文件,团队项目更省事
两种用法。一种是显式传入:
docker agent run agent.yaml --env-from-file .env
``.env的格式是每行一个KEY=VALUE,支持 #注释、带引号的值和空行,官方明确要求把它加进.gitignore`。
另一种是全局默认文件 ~/.config/cagent/.env,每次运行自动读取。它由 docker agent setup 写入,权限 0600 但内容是明文。路径还是老的 cagent 目录,因为 Docker Agent 在 Desktop 4.49 到 4.62 期间就叫 cagent。
方式三:Compose secrets,容器化部署的首选
容器化部署用 Compose secrets。每个 secret 单独存一个文件,compose 里引用:
services:
agent:
image: docker/docker-agent
command: run --exec /app/agent.yaml "Hello!"
secrets:
- ANTHROPIC_API_KEY
volumes:
- ./agent.yaml:/app/agent.yaml:ro
secrets:
ANTHROPIC_API_KEY:
file: ./.anthropic_api_key
Compose 会把文件挂到容器内的 /run/secrets/ANTHROPIC_API_KEY,Docker Agent 自动读取。CI 里更常见的写法是用 environment: 把宿主机的环境变量转发进 /run/secrets/:
secrets:
ANTHROPIC_API_KEY:
environment: "ANTHROPIC_API_KEY"
官方给了一张对比表:环境变量存在内存里,docker inspect 和进程列表都能看见;Compose secrets 挂成 tmpfs 文件,docker inspect 看不到。生产必须换。
方式四:Sandboxes 的 sbx secret,多厂商自动路由
在 Sandboxes 里跑 Docker Agent,官方让用存进宿主机钥匙串的方式:
sbx secret set openai
sbx secret set anthropic
sbx secret set google
sbx secret set xai
sbx secret set mistral
sbx secret set openrouter
只配想用的那几家,Docker Agent 会自动检测凭据并路由到厂商。secret 默认全局,加 --sandbox <名字> 只对某个沙箱生效,沙箱级优先。存放按系统分:macOS 钥匙串,Windows 凭据管理器,Linux Secret Service。
无桌面的 Linux 要留意。headless 服务器和部分 WSL 没有 Secret Service,sbx 会退回 ~/.config/com.docker.sandboxes 下的文件,权限 0700,并提示这个 secret 靠文件权限而非密码保护。这种环境建议改用 --command。
已经有环境变量的,一条命令搬进去,--dry-run 可预览:
sbx secret import --all
验证:三处检查确认 key 生效
配完先分层验证。第一层,sbx secret ls 列出 SCOPE、SERVICE、SECRET 三列,值只显示前后几位。
第二层,跑 sbx diagnose,它检查 CLI 二进制、daemon 可达性、版本匹配、存储目录和认证状态,给出汇总和修复建议。
第三层,真跑一个小任务。官方最短验证是用 --record 录一次:cagent run my-agent.yaml --record "What is Docker?",能返回说明 key 通了。录下之后用 --fake my-test 回放,调试不用再花 API 费用。

常见卡点:key 配了但读不到
按这个顺序查,命中率最高。
- 沙箱里 echo 是占位符:正常,说明代理工作正常。真实值不进沙箱,这是设计目标不是 bug。
- 报 401 且配置看着没问题:跑
sbx policy log看 PROXY 列。走 transparent 代理的请求不做凭据注入,通常是沙箱内客户端没配 forward 代理。 - 自定义变量名没生效:Anthropic 和 Google 支持
token_key改写变量名,其余厂商用默认名。token_key填的是变量名本身,不会被${env.X}展开。 - 模型引用大小写错了:模型引用区分大小写,
openai/gpt-5和openai/GPT-5不是一回事。 - 1Password 引用的值取不到:值以
op://开头时会调op read解析,CLI 没装或没登录就变空值并打警告,官方明确不会把原始op://发给厂商。先查op signin。
进阶:别把 key 写进 YAML
官方强调过:env、headers、URL 都能直接写明文 secret,但应该用 ${env.VAR} 引用在运行时解析,这是所有字段的通用语法。
还有一层防护默认开着:redact_secrets 会从工具调用参数、外发消息和工具输出里擦掉识别出的密钥,覆盖 GitHub PAT、云厂商凭据、各家平台令牌、JWT 和 PEM 私钥,命中替换成 [REDACTED],除非显式写 redact_secrets: false。
要复用组织已有的密钥系统,在 ~/.config/cagent/config.yaml 声明 credential_helper 指向 Vault 或 1Password CLI 就行,变量名会作为最后一个参数传入,值打到标准输出即可。
站内配合 Docker Agent cagent 安装教程 先把它装起来,撞上 429 就看 Docker Agent 429 报错排查,配置方式差异读 Docker Agent 和 Claude Code 哪个好。
更习惯直接改文件的,Codex CLI API Key 配置 那篇的 auth.json 思路可以对照。
官方依据集中在三页:Docker Agent 快速上手 给了环境变量与安装方式,密钥管理 给了六层优先级链和 Compose secrets 写法,Sandboxes 凭据 给了 sbx secret 的完整用法。
常见问题
Docker Agent 的 API Key 一定要付费吗
不一定。Docker Model Runner 本地跑模型,不需要 key 也没有调用费用,官方把它列为不需要 API key 的选项。Ollama、vLLM、LocalAI 这类本地推理同样不需要 key。要用 GPT、Claude、Gemini 这些托管模型才需要对应的付费 key。
为什么我在沙箱里 export 的 key 不生效
因为 Sandboxes 走宿主侧凭据代理。官方说明是发请求时宿主机代理拦截,查宿主机上存的凭据,覆写认证头再转发,沙箱里始终只有一个占位符。配 key 请用 `sbx secret set `,别在沙箱里 export。
sbx secret 存在哪里,安全吗
macOS 走系统钥匙串,Windows 走凭据管理器,Linux 走 Secret Service。headless Linux 和部分 WSL 没有 Secret Service,会退回 `~/.config/com.docker.sandboxes` 下的文件,权限 0700 但没有密码保护,`sbx` 会打印提示。这种环境建议用 `--ref` 或 `--command`。
redact_secrets 会不会把我的正常文本也打码
有小概率。官方说明规则覆盖 GitHub PAT、云厂商凭据、各类平台令牌、JWT 和 PEM 私钥,命中就替换成 [REDACTED],同时提醒留意漏报。某个 agent 确实要处理密钥类文本,就单独给它写 `redact_secrets: false`。

京ICP备2024094994号-29