Cloud Claw Launch Agent CLI 实战指南:用 altllm cloud-claw-deploy 一键启动 OpenClaw / PicoClaw / Ottie 自治代理
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 为每一个密钥参数都提供三种等价的注入方式:
- 直接 flag:
--telegram-bot-token <值>,直接把明文令牌写在命令行; - 环境变量选择器:
--telegram-bot-token-env TELEGRAM_BOT_TOKEN,从指定环境变量读取(前面的示例即此方式); - 文件选择器:
--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 模型体系,两端技能可以串成完整的“开通密钥 → 充值余额 → 启动代理”链路。