Cloud Claw Launch Agent CLI 实战指南:用 altllm cloud-claw-deploy 一键启动 OpenClaw / PicoClaw / Ottie 自治代理

原创2026-10-08 22:07:301,988 阅读

Cloud Claw Launch Agent CLI 实战指南:用 altllm cloud-claw-deploy 一键启动 OpenClaw / PicoClaw / Ottie 自治代理

本文围绕本仓库 cloud-claw-launch-agent 技能 的核心参考文档 cli-reference.md,完整讲解 Cloud Claw 新建部署(new deployment)工作流的全部 CLI 命令与约束。读完本文,你将掌握如何用本地 altllm cloud-claw-* 命令完成部署前上下文检查、OpenClaw / PicoClaw / Ottie 三种代理类型的一键启动、三种密钥注入方式,以及如何根据返回值与错误码精准定位启动失败原因。

Cloud Claw Launch Agent 是什么

Cloud Claw 是 AltLayer 生态中面向自治代理(autonomous agent)的托管部署服务,用户可以通过本地 CLI 命令复刻 Cloud Claw 网页端(UI)的新建部署表单语义,无需手写底层 HTTP 请求或触碰 GCP 构建/镜像脚本。在本仓库中,该工作流被封装为 cloud-claw-launch-agent 技能,其能力边界由 skill-map.md 明确圈定为两个命令:

Skill 覆盖命令 用途
cloud-claw-launch-agent cloud-claw-deploy、cloud-claw-me 封装部署表单语义与启动前检查
cloud-claw-manage-vm cloud-claw-deployments、cloud-claw-deployment、cloud-claw-start、cloud-claw-stop、cloud-claw-restart、cloud-claw-renew、cloud-claw-auto-renew、cloud-claw-delete、cloud-claw-logs 封装 Cloud Claw 用户侧 API 的 VM 生命周期管理

因此,本技能只负责新建部署;启动后的 start/stop/delete/logs 等生命周期任务应转交给 cloud-claw-manage-vm,不要在 cloud-claw-deploy 上扩展职责。

部署前检查:读取用户部署上下文

创建 VM 之前,必须先用 cloud-claw-me 检查当前用户(账号)的部署上下文,避免在配额、信用或套餐不允许的情况下盲目发起部署:

node dist/cli.js cloud-claw-me

返回结果中需要重点关注的字段及其业务含义:

字段 含义
altllmConnected 是否已连接 AltLLM 账户,未连接时 openclaw 付费路径可能不可用
altllmTier 当前 AltLLM 套餐层级(如 free / basic / pro / power / flex),决定可用的模型与配额
vmLimit 当前账号允许创建的 VM 上限
isFreeTier 是否为免费层级,免费层级通常受更强的配额与功能限制
activePayments 当前进行中的支付记录,可能影响新部署的结算判断
prices 各类部署的价格信息
credit 账户可用余额/信用额度,余额不足时部署会以 402 失败
freeSlots 剩余免费部署名额(免费槽位),槽位耗尽时新部署会失败

这些字段共同决定了“现在能否启动一个新的 OpenClaw / PicoClaw / Ottie”。从 skill-map.md 的源文件映射可以看出,其背后对应的是 cloud-claw 仓库中 server/src/routes/auth.ts(认证与账号上下文)与 server/src/services/altllm.ts(AltLLM 账号与套餐绑定)等服务逻辑,cloud-claw-me 正是用户侧 API 的 CLI 封装。

支持的 Agent 类型

部署的核心参数是 --agent-type,共三种取值,分别对应 Cloud Claw UI 中的三类代理,定义于 SKILL.md:

Agent 类型 内部取值(--agent-type) 用户侧说明
OpenClaw openclaw 付费路径,支持 Telegram + Web 控制台(dashboard)
PicoClaw picoclaw 仅 Telegram
Ottie aintern 仅 Telegram,自进化(self-evolving)分支

注意:Ottie 的内部取值是 aintern,与它的对外名称不同,这是最容易踩坑的一处映射。

启动 OpenClaw

OpenClaw 是功能最完整的付费路径,通过 --model 指定模型(UI 支持的 OpenClaw 模型为 altllm/altllm-standard 与 altllm/altllm-mega),并需要 Telegram 机器人令牌:

TELEGRAM_BOT_TOKEN=123456789:ABC... \
node dist/cli.js cloud-claw-deploy \
  --name happy-fox-12 \
  --agent-type openclaw \
  --model altllm/altllm-standard \
  --telegram-bot-token-env TELEGRAM_BOT_TOKEN \
  --telegram-allowed-users 123456789

这里通过 --telegram-bot-token-env TELEGRAM_BOT_TOKEN 将令牌以环境变量形式注入(具体见下文“密钥输入选项”)。--telegram-allowed-users 限定哪些 Telegram 用户可以与机器人交互,是面向私有/白名单场景的必填项。

启动 PicoClaw

PicoClaw 是仅 Telegram 的轻量路径,不指定 --model:

TELEGRAM_BOT_TOKEN=123456789:ABC... \
node dist/cli.js cloud-claw-deploy \
  --name swift-panda-58 \
  --agent-type picoclaw \
  --telegram-bot-token-env TELEGRAM_BOT_TOKEN \
  --telegram-allowed-users 123456789

启动 Ottie

Ottie 走 aintern 类型,同样仅 Telegram、同样必须携带 Telegram 机器人令牌:

TELEGRAM_BOT_TOKEN=123456789:ABC... \
node dist/cli.js cloud-claw-deploy \
  --name brave-owl-14 \
  --agent-type aintern \
  --telegram-bot-token-env TELEGRAM_BOT_TOKEN \
  --telegram-allowed-users 123456789

关于 --telegram-allowed-users 的重要约束

只有在你有意发布公开机器人时,才可以省略 --telegram-allowed-users。显式传入一个空值(--telegram-allowed-users "")会被 CLI 拒绝。也就是说:要么给出至少一个真实用户 ID,要么干脆不传(表示公开),不存在“传一个空字符串来留白”的中间态。

部署命名与参数约束

除上述命令示例外,SKILL.md 还补充了启动前必须满足的规则:

  • 部署 name 必须匹配正则 ^[a-z0-9-]+$,即只允许小写字母、数字与连字符,且最大长度 63 字符;
  • agentType(即 --agent-type)必须是 openclaw、picoclaw、aintern 三者之一;
  • picoclaw 与 aintern 都必须提供 TELEGRAM_BOT_TOKEN;
  • openclaw 使用 OPENCLAW_MODEL,UI 支持的取值是 altllm/altllm-standard 与 altllm/altllm-mega;
  • 后端可能为已登录用户自动注入 AltLLM API Key(即无需显式传 --altllm-api-key);
  • 启动成功与否取决于配额(quota)、免费槽位(free-slot)可用性、有效信用(credit)与支付状态(payment state)。

密钥输入选项(Secret Input Options)

部署涉及 Telegram 机器人令牌与可选的 API Key,CLI 为每一个密钥参数都提供三种等价的注入方式:

  1. 直接 flag:--telegram-bot-token <值>,直接把明文令牌写在命令行;
  2. 环境变量选择器:--telegram-bot-token-env TELEGRAM_BOT_TOKEN,从指定环境变量读取(前面的示例即此方式);
  3. 文件选择器:--telegram-bot-token-file /path/to/token.txt,从文件内容读取,适合令牌不落在 shell 历史或进程参数里的场景。

同一套模式同样适用于另外两个密钥参数:

  • --altllm-api-key(对应 -env / -file 变体同样可用)
  • --anthropic-api-key(对应 -env / -file 变体同样可用)

例如:

node dist/cli.js cloud-claw-deploy \
  --name happy-fox-12 \
  --agent-type openclaw \
  --model altllm/altllm-standard \
  --telegram-bot-token-file /path/to/token.txt \
  --anthropic-api-key-env ANTHROPIC_API_KEY \
  --telegram-allowed-users 123456789

实践建议:优先使用 -env 或 -file 变体,避免密钥明文出现在命令行参数与进程列表中。后端为已登录用户自动注入 AltLLM API Key 时,--altllm-api-key 可以省略。

成功的部署响应

部署成功时 CLI 返回如下结构的 JSON:

{
  "success": true,
  "deployment": {
    "name": "happy-fox-12",
    "vmName": "openclaw-happy-fox-12",
    "url": "/dash/happy-fox-12/"
  }
}

字段含义:

  • success:布尔值,是否为成功响应;
  • deployment.name:用户指定的部署名;
  • deployment.vmName:后端实际创建的 VM 名,格式为 <agent-type>-<name>(如 openclaw-happy-fox-12);
  • deployment.url:Web 控制台访问路径(/dash/<name>/),OpenClaw 类型可由此进入 dashboard。

常见启动失败:错误码与应对

部署失败时,CLI 应清晰地向用户呈现以下错误码及其业务含义:

错误码 含义 排查方向
401 认证失败 检查 cloud-claw-me 返回的 altllmConnected 与登录会话是否有效,重新完成 AltLLM 登录
400 PicoClaw 或 Ottie 缺少 Telegram 机器人令牌 确认 --telegram-bot-token(-env/-file) 已提供且值为非空
402 余额不足 / 需要支付(payment required) 核对 cloud-claw-me 的 credit 字段,为 AltLLM Portal 账户充值或领取促销码
409 VM 名称已存在 更换 --name(遵守 ^[a-z0-9-]+$ 且长度 ≤ 63),或先经 cloud-claw-manage-vm 清理同名旧 VM
429 VM 配额超限 核对 vmLimit 与 freeSlots,删除无用 VM 释放配额,或升级套餐

401 / 402 / 429 三类错误在发起 cloud-claw-deploy 之前,大多可以通过一次 cloud-claw-me 的字段(altllmConnected、credit、vmLimit、freeSlots)提前预判,因此“先 me 后 deploy”是本技能推荐的固定操作顺序。

在仓库中的定位与延伸阅读

本技能是 AltLayer altllm CLI 技能家族(altllm-portal-cli 伞技能,涵盖 auth、API keys、billing、payments、x402)中专门负责 Cloud Claw 新建部署的一支。与它相邻的职责边界如下:

  • 新建部署(本技能):cloud-claw-me + cloud-claw-deploy,对应 cli-reference.md;
  • VM 生命周期:cloud-claw-manage-vm 技能,负责启动、停止、续期、日志与 dashboard;
  • 账号与余额:altllm-portal-auth(钱包登录)、altllm-portal-billing(credit / 促销码 / 交易 / 用量分析)与 altllm-portal-payments(加密充值)为部署提供前置的登录、余额与套餐上下文——这也是 cloud-claw-me 中 altllmTier、credit 等字段的数据来源。

在 README.md 描述的分层栈中,Cloud Claw 属于执行层(Execution)的自治代理托管能力,与 AltLayer 的 AltLLM 推理网关(altllm-portal-api-keys 中描述的 https://api.altllm.ai/v1 OpenAI 兼容网关)配套使用:Portal 侧签发与充值,Cloud Claw 侧消费模型并承载代理运行。以 OpenClaw 部署为例,--model altllm/altllm-standard 即复用了同一套 AltLLM 模型体系,两端技能可以串成完整的“开通密钥 → 充值余额 → 启动代理”链路。

登录后查看全文
internet-court-skill