如何安全运行AI代理：Agent of Empires容器沙箱Docker、Podman与Apple Containers指南-育师

如何安全运行AI代理：Agent of Empires容器沙箱Docker、Podman与Apple Containers指南

【免费下载链接】agent-of-empiresManage multiple Claude Code, OpenCode agents from either TUI or Web for easy access on mobile. Also supports Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, Copilot CLI, Factory Droid Coding.项目地址: https://gitcode.com/gh_mirrors/ag/agent-of-empires

Agent of Empires（AoE）是一款AI代理管理工具，支持从 TUI 或 Web 仪表盘统一管理 Claude Code、OpenCode、Codex CLI、Gemini CLI 等多个编程AI代理，其核心安全能力是容器沙箱（Container Sandbox）：让AI代理在独立的 Docker、Podman 或 Apple Containers 容器中运行，代理能访问你的项目代码，却碰不到本机其余文件，实现"安全运行AI代理"的隔离目标。

为什么AI代理需要容器沙箱？

AI代理（编程Agent）会执行命令、读写文件、安装依赖，默认情况下它们拥有和你一样的主机权限。容器沙箱提供了天然的隔离层：

代码可达，系统隔离：项目目录挂载到容器内的/workspace，代理可以修改代码，但删不掉你主机上的其他文件
凭证自动注入：代理登录凭证被注入到每个会话私有的存储中，容器内无需重新登录
资源可控：可设置 CPU、内存上限，防止代理"失控"占满机器
清理彻底：删除会话时容器一并删除，不留残留

相关设计实现可在 src/containers/ 目录的运行时模块中查看，官方指南位于 docs/guides/sandbox.md。

快速上手：一条命令创建沙箱会话

安装好 tmux 和任意容器运行时后（Docker 为默认），只需一条命令：

aoe add --sandbox . # 使用官方默认沙箱镜像 aoe add --sandbox-image myregistry/custom:v1 . # 使用自定义镜像 aoe remove <session> # 删除会话时一并删除容器

在 TUI 或 Web 向导中创建会话时，直接勾选Sandbox 开关即可——只有检测到容器运行时后，该选项才会出现。

官方提供两款沙箱镜像

镜像	内容
`aoe-sandbox:latest`（默认）	所有受支持的代理 CLI + ACP 适配器、git、ripgrep、fzf
`aoe-dev-sandbox:latest`	基础镜像 + Rust、uv、Node LTS、GitHub CLI

需要项目专属依赖时，基于任一镜像扩展后通过--sandbox-image指定即可。

三大容器运行时：Docker、Podman、Apple Containers 怎么选？

Docker（默认运行时）

开箱即用，无需任何配置。[sandbox]下的所有运行策略选项 Docker 全部支持。

Podman（Linux 用户友好替代）

Podman 是无守护进程、支持 rootless 的 Docker 替代品。安装后只需一行配置：

[sandbox] container_runtime = "podman"

使用要点：

独立镜像存储：先用podman pull拉取沙箱镜像，或让 AoE 首次使用时自动拉取
rootless 网络：1024 以上的端口直接可用
SELinux 拦截挂载：若容器内出现 "Permission denied"，设置selinux_relabel = true即可

Apple Containers（macOS 原生运行时）

Apple Containers 基于 Apple 虚拟化框架，需要 Apple 芯片和 macOS 26（Tahoe）或更新版本：

brew install container container system start # 可能需要下载 Linux 内核

然后配置：

[sandbox] container_runtime = "apple_container"

TUI 的沙箱开关会自动使用该运行时，container守护进程未启动时会明确报错。注意两点：每个容器独占一个 VM，已占用的主机内存在重启或删除前不会释放；不支持只读挂载（只读卷会自动降级为读写并给出日志警告）。

沙箱配置选项速查

在 Web 仪表盘的Settings → Sandbox页面或config.toml中，常用选项如下：

选项	默认值	说明
`enabled_by_default`	`false`	新会话是否自动启用沙箱
`default_image`	`aoe-sandbox:latest`	使用的沙箱镜像
`container_runtime`	`docker`	`docker`/`podman`/`apple_container`（仅全局生效）
`auto_cleanup`	`true`	删除会话时自动删除容器
`cpu_limit`/`memory_limit`	无	单容器资源上限，如`"4"`与`"8g"`
`environment`	`[]`	注入容器的环境变量
`mount_ssh`	`false`	只读挂载`~/.ssh/`
`default_terminal_mode`	`"host"`	配对终端运行位置

环境变量支持三种写法，密钥可以留在 shell 配置文件中而不写入配置文件：

[sandbox] environment = [ "ANTHROPIC_API_KEY", # 从主机透传同名变量 "GH_TOKEN=$AOE_GH_TOKEN", # 读主机变量 AOE_GH_TOKEN，注入为 GH_TOKEN "CUSTOM_API_KEY=sk-sandbox-key", # 字面量 ]

安全细节：代理能碰到什么、碰不到什么

自动挂载清单（这是沙箱的信任边界）：

主机路径	容器路径	模式
项目目录	`/workspace`	读写
`~/.gitconfig`	`/root/.gitconfig`	只读
`~/.ssh/`（开启`mount_ssh`时）	`/root/.ssh/`	只读
会话工件目录	`/aoe/artifacts`	读写
会话私有代理配置	`/root/.claude/`等	读写

几个值得了解的安全设计：

每会话私有代理存储：每个沙箱会话拥有独立的sandbox-v2/<instance-id>配置目录，会话的对话记录、缓存、日志彼此隔离，也绝不导入你主机的历史数据
文件夹预信任：容器内的工作区对代理而言是"陌生目录"，AoE 会在下发给容器的配置中预先信任它，避免代理因信任提示而卡住
共享凭证链：Claude Code 的刷新令牌会轮换失效，因此所有 Claude 会话共享一份sandbox-v2/.credentials.json，任一容器刷新后全体可见，登录一次即可
清理有兜底：aoe sandbox reclaim先报告再删除，避免误删包含代理凭证的存储

常见问题排查 🔧

容器被 OOM 杀掉：docker inspect显示OOMKilled: true。macOS 上 Docker 运行在内存上限固定（默认 2GB）的 Linux VM 中，请在 Docker Desktop 的Settings → Resources中调高 VM 内存（编程代理建议 8GB 以上），并设置[sandbox] memory_limit给每个容器明确配额。

沙箱镜像升级后 OpenCode 会话启动失败：报 drizzle/SQLite 迁移错误。删除该会话沙箱数据库（位于~/.local/share/opencode/sandbox-v2/<instance-id>/opencode.db*）并重启即可，主机上的 OpenCode 状态不受影响。

Podman 下podman info失败：通常是存储未初始化，或缺少 rootless 模式所需的/etc/subuid、/etc/subgid条目。

完整排查方案见 docs/guides/sandbox.md，运行时探测逻辑实现于 src/containers/runtime.rs。