一天一个开源项目（第88篇）：Tank-OS —— 用 bootc 把 AI Agent 装进可启动 Linux 镜像，TaoToken 统一 Key 接入实测

1. 为什么要把 AI Agent 装进可启动镜像

AI Agent 在企业里落地，最先撞上的不是模型能力问题，而是运行环境问题。你在本地笔记本上跑得好好的 Agent，换到测试机、生产机、边缘设备上，行为可能完全不一样：Python 版本差一点、系统库少一个、API Key 放在哪个文件里、谁有权限读它，全是坑。Tank-OS 这个项目给出的答案很直接——把 Agent、运行时、操作系统、Systemd 单元和升级机制全部打包进一个 OCI 容器镜像，然后让整台机器从这个镜像启动。这就是 bootc（Boot Container）的核心思路，也是本文要拆解的重点。

Tank-OS 是什么？简单说，它是一个基于 Fedora bootc 的可启动 Linux 镜像，里面预装了 OpenClaw AI Agent 的运行环境，用 rootless Podman Quadlet 管理容器生命周期，用 Podman secret store 加密存储 API Key。它适合谁？适合需要在多台机器上统一部署 AI Agent 的企业 IT 管理员、对不可变基础设施感兴趣的 DevOps 工程师，以及想研究 Agent 隔离方案的开发者。它能做什么？一句话：让每台机器上的 Agent 环境完全一致、凭证不落明文、更新可原子回滚。

我试过在本地 VM 里从零构建一个类似的 bootc 镜像，整个过程比想象中顺，但有几个配置点如果没注意，启动后 Agent 就是连不上模型服务。下面我把构建配置、TaoToken 统一 Key 接入、启动验证和常见报错排查完整走一遍，你可以直接跟着操作。

2. TaoToken 前置准备：统一 Key 与 API 通道

在把 Agent 装进镜像之前，先要把模型服务的接入方式定下来。Tank-OS 里的 OpenClaw Agent 需要调用大模型 API，如果每台机器都单独配 Key、单独改 Base URL，那镜像统一分发的意义就没了。所以正确做法是：用一个统一的 API 通道，所有 Agent 实例共用同一套接入配置，Key 通过 secret 注入而不是烘焙进镜像。

TaoToken 在这里扮演的就是统一 Key/API 通道的角色。它提供兼容 OpenAI 风格的接口，Base URL 是https://taotoken.net/api，你只需要一个 Key，就能在多个 Agent 实例、多台机器之间复用同一套模型接入配置。这对 bootc 镜像场景特别合适：镜像里只写 Base URL 和模型 ID，Key 通过 cloud-init 或 Podman secret 在首次启动时注入，镜像本身不含任何敏感信息。

前置准备分三步。第一步，拿到 API Key。访问 TaoToken API Keys 页面 创建或复制你的 Key，格式通常是sk-开头的一串字符。第二步，确认你要用的模型 ID。不同模型对应不同的 ID 字符串，比如claude-sonnet-4-20250514这类，具体以 模型对话页面 展示的为准。第三步，确认接入文档里的请求格式，接入文档 里有完整的 endpoint 说明和示例。

这里有个关键点：Tank-OS 的 Quadlet 单元里，API Key 是通过Secret=openclaw-api-key,type=env,target=OPENCLAW_API_KEY注入的，也就是说 Agent 进程读的是环境变量OPENCLAW_API_KEY。所以你在配置 Agent 时，要让它从这个环境变量取值，而不是去读某个.env文件。Base URL 则可以直接写在 Agent 的配置文件或环境变量里，因为它不敏感。

如果你打算长期跑 Agent 舰队，建议用 Coding Plan 这类套餐来管理调用额度，比按次计费更适合持续运行的场景。配置完成后，先在本地用 curl 验证一下 Key 和 Base URL 是否可用，再往镜像里塞，能省掉很多启动后排查的时间。

3. 可复制配置：bootc 镜像构建与 Agent 环境变量

这一节是全文的核心，给出可以直接复制的配置片段。整个构建流程分四块：Containerfile、Quadlet 单元、cloud-init 配置、以及构建 QCOW2 磁盘的命令。

3.1 Containerfile：基于 Fedora bootc 构建

Tank-OS 的 Containerfile 基于quay.io/fedora/fedora-bootc:latest，这是 Fedora 官方维护的 bootc 基础镜像。下面是我整理的可复制版本，去掉了项目特有的部分，保留通用结构：

FROM quay.io/fedora/fedora-bootc:latest # 安装必要软件包 RUN dnf install -y \ podman \ openssh-server \ cloud-init \ python3 \ shadow-utils \ sudo \ vim \ && dnf clean all # 创建 openclaw 用户（UID/GID 1000） # 配置 subuid/subgid 范围用于 rootless Podman RUN useradd -m -u 1000 -g 1000 openclaw && \ usermod -aG wheel openclaw && \ echo "openclaw:100000:65536" >> /etc/subuid && \ echo "openclaw:100000:65536" >> /etc/subgid # 启用 cloud-init 服务族和 sshd RUN systemctl enable \ cloud-init-local.service \ cloud-init-network.service \ cloud-init.service \ cloud-config.service \ cloud-final.service \ sshd.service # 注入自定义脚本和 Quadlet 单元 COPY bootc/ /

注意 subuid/subgid 的写法，我用的是openclaw:100000:65536这种带用户名的格式，比只写数字范围更明确。如果你在别的教程里看到echo "100000:65536" > /etc/subuid，那种写法在某些 Fedora 版本上会导致 rootless Podman 启动失败，因为缺少用户名映射。

3.2 Quadlet 单元：声明 Agent 容器

Quadlet 是 Podman 4.4+ 的特性，用 Systemd unit 语法声明容器。文件放在/etc/containers/systemd/users/1000/openclaw.container：

[Unit] Description=OpenClaw AI Agent Service After=network-online.target [Container] Image=ghcr.io/openclaw/openclaw:latest ContainerName=openclaw UserNS=keep-id:uid=1000,gid=1000 Volume=%h/.openclaw:/home/openclaw/.openclaw:z Secret=openclaw-api-key,type=env,target=OPENCLAW_API_KEY Environment=OPENCLAW_BASE_URL=https://taotoken.net/api Environment=OPENCLAW_MODEL_ID=claude-sonnet-4-20250514 [Service] Restart=always [Install] WantedBy=default.target

这里三件套齐了：Base URL 是https://taotoken.net/api，Key 通过Secret注入为环境变量OPENCLAW_API_KEY，Model ID 通过OPENCLAW_MODEL_ID指定。UserNS=keep-id保证容器内 UID 1000 映射到宿主 UID 1000，配合 rootless 模式实现隔离。

3.3 cloud-init 配置：首次启动注入 Key

cloud-init 的 user-data 负责在首次启动时把 API Key 写入 Podman secret store。创建一个user-data文件：

#cloud-config users: - name: openclaw groups: wheel ssh_authorized_keys: - ssh-ed25519 AAAA...你的公钥... runcmd: - su - openclaw -c "podman secret create openclaw-api-key /run/openclaw-key" - su - openclaw -c "systemctl --user daemon-reload" - su - openclaw -c "systemctl --user start openclaw.service" write_files: - path: /run/openclaw-key content: | sk-你的TaoTokenKey permissions: '0600' owner: root:root

Key 写在/run/openclaw-key这个临时文件里，podman secret create读取后加密存入 secret store，然后这个临时文件在重启后就消失了。这样 Key 不会以明文形式留在磁盘上。

3.4 构建 QCOW2 磁盘镜像

用bootc-image-builder把容器镜像转成可启动的 QCOW2 磁盘：

mkdir -p out-tank-os sudo podman run \ --rm \ --privileged \ --pull=newer \ -v ./config.json:/config.json \ -v ./out-tank-os:/output \ -v /var/lib/containers/storage:/var/lib/containers/storage \ quay.io/centos-bootc/bootc-image-builder:latest \ --type qcow2 \ --config /config.json \ quay.io/yourname/tank-os:latest

构建完成后，out-tank-os/qcow2/disk.qcow2就是可启动的磁盘镜像。用qemu-system-x86_64或 VirtualBox 启动它，或者用virt-install导入到 KVM。

4. 验证请求：启动后确认 Agent 调用链路

镜像构建好、VM 启动后，接下来要验证 Agent 是否真的能通过 TaoToken 调通模型。这一步不能跳过，因为 bootc 镜像的启动流程和普通 Linux 不一样，很多配置问题只有在启动后才能暴露。

4.1 SSH 登录并检查服务状态

用 cloud-init 里配置的 openclaw 用户登录：

ssh openclaw@<vm-ip>

登录后先看 Quadlet 生成的服务是否在跑：

systemctl --user status openclaw.service

正常输出里应该有Active: active (running)。如果显示inactive或failed，用journalctl --user -u openclaw -n 50看日志。

4.2 确认环境变量注入成功

进入容器检查环境变量：

podman exec openclaw env | grep OPENCLAW

你应该看到三行：

OPENCLAW_API_KEY=sk-... OPENCLAW_BASE_URL=https://taotoken.net/api OPENCLAW_MODEL_ID=claude-sonnet-4-20250514

如果OPENCLAW_API_KEY是空的，说明 secret 没注入成功，回到第 5 节排查。

4.3 用 curl 验证模型调用

在容器内直接 curl TaoToken 的接口，确认网络和 Key 都通：

podman exec openclaw curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $OPENCLAW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

如果返回 JSON 里包含choices字段和模型回复内容，说明调用链路通了。如果返回 401，是 Key 问题；如果返回连接超时，是网络或 Base URL 问题。

4.4 运行 Agent 自带健康检查

OpenClaw 提供了doctor命令做端到端检查：

openclaw doctor

这个命令会依次检查：容器运行状态、环境变量、模型 API 连通性、secret 可读性。输出里每一项前面有绿色对勾就表示通过。如果某一项失败，它会给出具体的错误信息和修复建议。

4.5 查看 Dashboard 和已连接设备

openclaw dashboard --no-open openclaw devices list

dashboard会输出一个本地访问地址，你可以在浏览器里打开看 Agent 的运行面板。devices list显示当前连接到这个 Agent 实例的设备。这两个命令能跑通，说明 Agent 的完整调用链路已经就绪。

5. 本篇常见错排查：401、local proxy failed、reading choices

这一节对照真实报错，给出排查路径。这些错误我在构建和启动过程中都遇到过，按顺序排查基本能定位。

5.1 401 Unauthorized

最常见的报错，返回体通常是：

{"error": {"message": "Invalid API key", "type": "invalid_request_error"}}

排查顺序：第一，确认podman exec openclaw env | grep OPENCLAW_API_KEY输出的 Key 和你 TaoToken 后台的一致，注意有没有多余空格或换行。第二，确认 secret 创建时读取的文件内容没有尾部换行，podman secret create会把文件内容原样存入，如果文件末尾有\n，Key 就会带一个换行符导致认证失败。第三，确认 Key 没有过期或被禁用，去 API Keys 页面 检查状态。

修复方法：删除旧 secret 重新创建。

podman secret rm openclaw-api-key printf '%s' 'sk-你的Key' | podman secret create openclaw-api-key - systemctl --user restart openclaw.service

用printf '%s'而不是echo，就是为了避免尾部换行。

5.2 local proxy failed

这个报错通常出现在 Agent 尝试通过本地代理访问外部 API 时：

Error: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused

原因是 Agent 的环境变量里残留了HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地代理。在 bootc 镜像里，这些变量可能来自基础镜像或 cloud-init 配置。排查方法：

podman exec openclaw env | grep -i proxy

如果有输出，在 Quadlet 单元的[Container]段里显式清空：

Environment=HTTP_PROXY= Environment=HTTPS_PROXY= Environment=NO_PROXY=taotoken.net

然后systemctl --user daemon-reload && systemctl --user restart openclaw.service。

5.3 reading choices 相关报错

这个报错长这样：

Error: failed to parse response: reading choices: unexpected end of JSON input

它表示 Agent 收到了一个空响应或非 JSON 响应，但期望解析choices字段。常见原因有三个。第一，Base URL 写错了，比如写成了https://taotoken.net而不是https://taotoken.net/api，导致请求打到了首页返回 HTML。第二，模型 ID 不存在，服务端返回了错误结构而不是标准的choices。第三，请求被中间层拦截返回了空体。

排查方法：先用第 4.3 节的 curl 命令手动请求一次，看返回的原始内容是什么。如果是 HTML，就是 Base URL 问题；如果是{"error": ...}，就是模型 ID 或 Key 问题。确认 Base URL 必须是https://taotoken.net/api，模型 ID 去 模型对话页面 核对。

5.4 OAuth 相关报错

如果你用的是需要 OAuth 流程的模型服务，可能会遇到：

Error: OAuth token exchange failed: invalid_grant

Tank-OS 场景下，OAuth 通常不适用于 API Key 模式。如果你在 Agent 配置里启用了 OAuth 但实际用的是 Key 认证，把认证方式切回 API Key 即可。检查 Agent 配置文件里有没有auth_type: oauth之类的字段，改成auth_type: api_key。

5.5 Quadlet 服务启动失败

如果systemctl --user status openclaw.service显示 failed，但日志里没有明显错误，检查 Quadlet 文件路径是否正确。对于 UID 1000 的用户，路径必须是/etc/containers/systemd/users/1000/openclaw.container。路径错了 Systemd 不会报错，只是不生成服务。改完后执行：

systemctl --user daemon-reload systemctl --user start openclaw.service

5.6 bootc 更新后 Agent 状态丢失

执行bootc upgrade --apply后，如果发现 Agent 的会话历史没了，检查可变层目录是否被正确挂载。~/.openclaw/应该是持久化的，如果它被写到了/usr/或/etc/下面，更新时就会被覆盖。确认 Quadlet 单元里的Volume=%h/.openclaw:/home/openclaw/.openclaw:z这一行存在且路径正确。

6. 把 Agent 装进镜像之后：统一 Key 接入的长期价值

走到这一步，你已经有了一个可启动的 Tank-OS 镜像，Agent 环境固化在里面，API Key 通过 secret 注入，模型调用走 TaoToken 统一通道。这套组合的价值不在于单次部署，而在于长期运维。

当你需要管理十台、几十台 Agent 机器时，传统方案是每台机器单独配 Key、单独改配置、单独升级依赖，任何一台出问题都要 SSH 上去手动修。而 bootc 方案下，你只需要构建一个新镜像，推送到 registry，然后在每台机器上执行bootc upgrade --apply，整台机器的 OS 和 Agent 一起原子更新，失败自动回滚。Key 不用动，因为它不在镜像里，而在每台机器的 secret store 里。

TaoToken 在这个架构里的角色是统一接入层。所有 Agent 实例共用同一个 Base URL 和同一套模型 ID 配置，Key 虽然每台机器单独注入，但都来自同一个 TaoToken 账号，调用额度、模型权限、用量统计都在一个地方管理。如果你要换模型，改 Quadlet 单元里的OPENCLAW_MODEL_ID然后重启服务即可，不用重新构建镜像。

如果你还在本地开发阶段，可以先用 模型对话页面 快速验证模型可用性，确认没问题再往镜像里配。如果你打算把这套方案用到生产环境，建议从 Coding Plan 入手，额度管理更清晰。完整的接入参数和 endpoint 说明在 接入文档 里，配置前过一遍能少踩很多坑。

最后说一个实操细节：构建镜像时，把OPENCLAW_BASE_URL和OPENCLAW_MODEL_ID写进 Quadlet 单元，但不要把 Key 写进去。Key 永远通过 cloud-init 或手动podman secret create注入。这样你的镜像可以公开分发，不用担心泄露凭证。这个习惯一旦养成，后面管理再多机器都不会乱。