教程2026-11-13 · 智涌AI

自托管 Claude Managed Agents 部署教程:从 Compose 到 Helm

自托管 Claude Managed Agents 部署教程头图:左侧大字「自托管 Managed Agents」与 8400 端口、10 个 worker、PostgreSQL 16+ 数据卡;右侧终端显示 docker compose 起栈、readyz 返回 ready、ant 建 Agent 开会话并返回 cma-sandbox 主机名

Anthropic 11 月 12 日推出了自托管版 Claude Managed Agents,Agent 定义、会话和会话历史都可以留在自己的服务器上。发布包要找 Anthropic 客户团队申请,拿到以后怎么起?这篇按官方快速入门、Kubernetes 部署页和差异文档整理:先用 Docker Compose 在一台机器上跑通第一个会话,再看生产环境的 Helm 部署要准备什么,以及从托管版迁过来要改哪些地方。

先弄清楚它自托管的是哪一层

自托管的是 Managed Agents 这套服务本身:服务端、PostgreSQL 数据库,以及给每个会话单独开沙箱的 worker。Claude 模型不在本地跑,推理请求默认还是发给 Claude API,也可以在服务端设置里改成云厂商或自建的模型网关。事件本身的介绍见站内快讯 Claude Managed Agents 能自托管了。

部署方式适合组成要注意
Docker Compose开发、试用服务端 + PostgreSQL + 10 个 worker明文 HTTP,默认只开本机 8400 端口
Kubernetes(两个 Helm chart)生产,官方推荐cma-server + cma-sandboxes,数据库放集群外需要 gVisor 节点和 NetworkPolicy

前置条件

官方特别提醒:Agent 的工具在这台主机的容器里运行,Docker Engine 28.3.3 之前的某些版本还可能让局域网里的机器连到 8400 端口。所以开发栈要放在一台没有重要数据的机器上。

第一步:解压并写好 .env

tar -xzf <archive>.tar.gz && cd <archive>/compose
cat > .env <<EOF
CMA_PG_PASSWORD=$(openssl rand -hex 32)
ANTHROPIC_API_KEY=sk-ant-...
CMA_SERVER__API_KEY=$(openssl rand -hex 32)
CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
EOF
chmod 600 .env

用编辑器把 sk-ant-... 换成自己的 Claude API 密钥。另外三项是自动生成的:数据库密码、应用调用这台服务器用的服务端 API 密钥,以及加密已存凭据的密钥。umask 比 022 严的话,解压出来的二进制会丢掉执行权限,服务端容器起不来,先把 umask 设回 022 再解压。

如果是让 Claude Code 代跑这份快速入门,官方的要求是:.env 由人自己编辑,Agent 不索要密钥,也不打印 .env。

第二步:起栈并检查就绪

docker compose up --build -d
docker compose logs -f cma-server   # 看到 msg="cma-server listening" 后 Ctrl+C
curl -s http://127.0.0.1:8400/cma-server/readyz

返回 "status":"ready" 就可以了。刚启动的几秒可能是 degraded;一直不变或返回 not_ready,就到返回里找状态为 failed 的检查项:upstream 说明 Claude API 拒绝了密钥,database 说明数据库登录或连接有问题。服务端始终起不来时,先看 docker compose logs migrate,这个一次性容器负责建表,必须以状态 0 退出。

第三步:建 Agent,跑第一个会话

另开一个终端专门跑 ant,让它指向自己的服务器。注意这里的 ANTHROPIC_API_KEY 填的是服务端 API 密钥:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

把下面内容存成 quickstart-agent.md,再执行 ant apply --yes quickstart-agent.md。命令会先报一条找不到组织和工作区的 404 警告,在自己的服务器上属于正常现象。

---
name: Quickstart agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant.

然后取出 Agent 和环境的 ID,开会话并连进去。Compose 栈的环境名叫 compose-sandbox:

AGENT_ID=$(ant beta:agents list --format raw \
  --transform 'data.#(name=="Quickstart agent").id' --raw-output)
ENVIRONMENT_ID=$(ant beta:environments list --format raw \
  --transform 'data.#(name=="compose-sandbox").id' --raw-output)
SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)
ant beta:sessions connect "$SESSION_ID"

在聊天界面里让它用 bash 工具执行 hostname。回复的主机名以 cma-sandbox- 开头,说明命令是在沙箱容器里跑的,没碰你的主机。回到第一个终端执行 docker ps --filter label=cma-server.sandbox,能看到这个容器;一轮对话结束大约一分钟后它会退出,下一条消息再起新容器。

两个终端分开用:带着 ANTHROPIC_BASE_URL 的那个终端里一旦执行 docker compose up,服务端就会调自己,而不是去调 Claude API。

常见坑

上生产:Kubernetes 要先备齐这些

生产用发布包里的两个 Helm chart:cma-server 在 cma-server 命名空间里跑建表任务和两个服务端实例;cma-sandboxes 在 cma 命名空间里跑调度器,给每个会话单独开一个沙箱 Pod。官方示例用的是 GKE,其他集群步骤相同,集群前提和部分 chart 参数不同。开工前要有:

凭据加密密钥要自己留一份。卸载 chart 会连 Secret 一起删掉,数据库虽然还在,没有这把密钥就用不了。卸载时先停调度器、删沙箱,因为 helm uninstall 会删掉约束沙箱的网络策略,已经开出来的沙箱却还在跑。

从托管版迁过来,要改的地方

托管版上的东西不会复制过来,Agent、Skill、凭据和记忆库都得在自己的服务器上重建。差异文档里影响最大的几条:

托管版做法自托管版替代做法
Files API、file 资源不支持文件放进 worker 工作目录;图片、PDF 用 base64 发
预置 docx/pdf/pptx/xlsx Skill拒绝保存从 skills 仓库下源码,当自定义 Skill 上传
定时部署、Webhook没有自己的 cron 开会话;靠事件流跟进
mcp_oauth 凭据拒绝创建改存 static_bearer,过期前自己换令牌
MCP 服务器、网页工具默认全关在 mcp.allowed_hostnames 里逐个列主机;web_tools.enabled: true

还有两处容易漏:MCP 主机名精确匹配,不支持通配符和子域名,没列进白名单的,服务端会拒绝保存引用它的 Agent;网页工具开了以后,web_search 也只在推理提供方为 anthropic、vertex、foundry 时可用,其他提供方下 Agent 照样保存,模型却调不到它,也不报错。自托管版多出来的能力包括单点登录、接自己的密钥管理器,以及给 MCP 调用签短期身份令牌。如果之前用 EKS 给编码 Agent 建沙箱那套思路做过隔离,可以对照着看自托管版的网络策略怎么配。

完成标准

最后

拿到发布包后,先在一台空机器上把 Compose 栈跑到 hostname 返回 cma-sandbox- 这一步,再按差异表盘点自己的 Agent 要改什么,然后再碰 Helm。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。