Docker Agent API Key 配置:4 种方式与验证封面图
Agent 与 Skills约 8 分钟

Docker Agent API Key 配置:4 种方式与验证

AI 指南··◉ 0 浏览

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

Docker Agent 官方文档首页截图

先分清两套配置体系

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 设成无效值,那会打乱代理注入。

Docker Agent API 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 费用。

sbx secret set 交互流程截图:选择服务、输入值、写入系统钥匙串

常见卡点: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`。

评论 (0)

?
0/1

还没有评论,来发第一条吧

网站上的服务均为第三方提供,
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策