使用AgentBay CLI创建和管理自定义镜像-无影 Agent 开发套件 AgentBay-阿里云-无影 Agent 开发套件 AgentBay(AgentBay)-阿里云帮助中心

AgentBay CLI 是管理 AgentBay 云端开发环境的命令行工具，适用于需要在 CI/CD 流水线中自动化管理镜像、批量操作的场景。本文介绍安装方法、快速入门流程、命令参考、环境切换及常见问题排查。

简介

主要功能

认证管理：基于 OAuth 的安全登录机制，支持阿里云账号集成。
镜像管理：浏览、创建、激活、停用和删除自定义镜像，查看镜像状态。
镜像创建：支持云上构建和本地构建两种模式。
镜像激活：激活自定义镜像实例，支持自定义资源、网络配置和生命周期管理。
镜像停用：停用已激活的镜像实例，释放资源。
模板下载：从云端下载 Dockerfile 模板。
API Key 管理：创建 API Key，设置并发限制。
Skill 管理：推送本地 Skill 到云端，按 ID 查看详情。
配置管理：令牌安全存储和自动刷新。
网络管理：列出已创建的网络包信息。
镜像状态：查看镜像的构建状态和资源状态。

支持的镜像类型

当前版本的 CLI 工具仅支持创建和激活 CodeSpace 类型的自定义镜像。image list 输出中的 TYPE 列显示底层分类（如 DockerBuilder 或 DedicatedDesktop），与 CLI 操作无关。

安装

通过 Tap 安装（推荐）

快速安装

# 1. 添加 AgentBay Cloud 的 Homebrew tap
brew tap aliyun/agentbay

# 2. 安装 agentbay 命令行工具
brew install agentbay

# 3. 验证安装
agentbay version

使用方法

安装完成后，可以使用以下命令：

# 查看版本信息
agentbay version

# 查看帮助信息
agentbay --help

# 使用 AgentBay 命令
agentbay [command] [options]

更新和卸载

更新到最新版本：

# 方式一：仅更新 agentbay
brew upgrade agentbay

# 方式二：方式一未生效时可尝试
git -C $(brew --repository aliyun/agentbay) pull && brew upgrade agentbay

# 方式三：前两种方式均未生效时可尝试
brew update
brew reinstall agentbay

卸载：

# 卸载 agentbay
brew uninstall agentbay

# 移除 tap（可选）
brew untap aliyun/agentbay

故障排查

1. 安装失败

# 更新 Homebrew
brew update

# 清理缓存
brew cleanup

# 重新安装
brew reinstall agentbay

2. 网络问题

Formula 已配置中国镜像源。如果仍有问题：

# 设置 Go 代理
export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn

# 重新安装
brew reinstall agentbay

3. 权限问题

# 修复 Homebrew 权限
sudo chown -R $(whoami) $(brew --prefix)/*

手动下载安装

从 GitHub Releases 页面下载对应平台的最新版本。

快速开始

1. 登录

首先需要登录到 AgentBay。CLI 会自动打开浏览器进行阿里云认证，完成登录后返回终端。

agentbay login

2. 查看可用镜像

# 仅列出自定义镜像（默认）
agentbay image list

# 包含系统镜像与自定义镜像
agentbay image list --include-system

# 仅显示系统镜像
agentbay image list --system-only

3. 下载 Dockerfile 模板

下载 Dockerfile 模板到当前目录。必须指定源镜像 ID，可通过 agentbay image list --system-only 查看可用系统镜像 ID：

agentbay image init --sourceImageId code-space-debian-12

4. 创建自定义镜像

4.1 云上构建

agentbay image create myapp --dockerfile Dockerfile --imageId code-space-debian-12

4.2 本地构建

登录无影 ACR（阿里云容器镜像服务）Docker 镜像仓库，获取镜像上传地址：

agentbay docker login

Credential expires at: 2026-05-11 12:28:55
Image registry path:   <your-registry-address>

WARNING! Your credentials are stored unencrypted in '/home/moushuai.ms/.docker/config.json'.
Configure a credential helper to remove this warning. See
https://docs.docker.com/go/credential-store/

Login Succeeded

Note: Credentials will expire after the time above. You can run 'agentbay docker login' again to refresh.
Note: When tagging images, use: <your-registry-address>:<your-tag>

本地构建 Docker 镜像：

docker build -t <your-registry-address>:<your-tag> Dockerfile .

将本地 Docker 镜像 push 到 ACR 仓库：

docker push <your-registry-address>:<your-tag>

从本地镜像创建 imgc 业务镜像：

agentbay image create-from-template \
  --sourceImage /customer_cli/<your-account-id>:<your-tag> \
  --name myApp \
  --template code-space-debian-12

5. 激活镜像

自定义镜像使用前需要激活，系统镜像无需激活。激活自定义镜像，使其可用于部署：

agentbay image activate imgc-xxxxx...xxx

6. 停用镜像

使用完毕后停用自定义镜像以节约资源。停用已激活的自定义镜像，释放相关资源：

agentbay image deactivate imgc-xxxxx...xxx

7. 创建 API Key

agentbay apikey create --name "my-api-key"

8. 会话并发设置

agentbay apikey concurrency set --api-key-id ak-xxx --concurrency 10

命令参考

全局选项

所有命令都支持以下全局选项：

--help, -h：显示命令帮助信息。
--verbose, -v：启用详细输出模式，显示调试信息。
--version：显示 CLI 版本信息。

命令结构

agentbay [全局选项] <命令> [命令选项] [参数]

命令索引

AgentBay CLI 的命令按功能分为以下章节，方便快速查找：

命令	说明
`login` / `logout`	认证管理 - 登录和登出。
`version`	显示 CLI 版本信息。
`image`	镜像管理 - 列出、创建、激活、停用和删除镜像。
`network`	网络包管理 - 列出网络包。
`apikey`	API Key 管理 - 创建 API Key，设置并发限制。
`skills`	Skill 管理 - 推送 Skill 到云端，查看详情。

镜像管理

镜像激活与停用说明

自定义镜像：使用之前需要激活，激活后可用于部署。
系统镜像：始终可用，无需激活。
停用镜像：使用完毕后停用自定义镜像以节约资源，停用已激活的自定义镜像会释放相关资源。

image list - 列出镜像

列出可用的 AgentBay 镜像。

语法

agentbay image list [选项]

选项

--os-type, -o <类型>：按操作系统类型过滤（Linux、Android、Windows）。
--include-system：同时显示自定义镜像和系统镜像。
--system-only：仅显示系统镜像。
--page, -p <数字>：页码（默认：1）。
--size, -s <数字>：每页显示数量（默认：10）。

示例

# 列出自定义镜像
agentbay image list

# 列出 Linux 镜像
agentbay image list --os-type Linux

# 列出所有镜像（自定义 + 系统）
agentbay image list --include-system

# 仅列出系统镜像
agentbay image list --system-only

# 分页查询
agentbay image list --page 2 --size 5

输出说明

命令输出包含以下列：

IMAGE ID：镜像唯一标识符。
IMAGE NAME：镜像名称。
TYPE：镜像类型（DockerBuilder 或 DedicatedDesktop）。
STATUS：镜像状态。
OS：操作系统类型和版本。
APPLY SCENE：应用场景。

状态说明

Creating：镜像正在构建中。
Available：镜像构建完成，可以激活。
Activated：已激活，运行中。
Create Failed：镜像构建失败。

重要

image list 命令只显示镜像的构建状态（Creating、Available、Create Failed），不显示激活/停用状态。激活和停用状态只在执行 image activate 或 image deactivate 命令时显示。

说明

系统镜像始终可用，无需激活。
用户创建的镜像需要激活后才能使用。
默认情况下仅显示自定义镜像。
镜像列表按自定义镜像和系统镜像分组显示。

image init - 下载 Dockerfile 模板

从云端下载 Dockerfile 模板到当前目录。必须指定源镜像 ID。

语法

agentbay image init --sourceImageId <镜像ID>

示例

# 下载 Dockerfile 模板
agentbay image init --sourceImageId code-space-debian-12

输出示例

[INIT] Downloading Dockerfile template...
Requesting Dockerfile template... Done.
Downloading Dockerfile from OSS... Done.
Writing Dockerfile to /path/to/current/directory/Dockerfile...
[WARN] Dockerfile already exists at /path/to/current/directory/Dockerfile
[INFO] The existing file will be overwritten.
 Done.
[SUCCESS] Dockerfile template downloaded successfully!
[INFO] Dockerfile saved to: /path/to/current/directory/Dockerfile
[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.

说明

如果当前目录已存在 Dockerfile，命令会覆盖现有文件，覆盖前会显示警告信息。
此步骤为可选操作，也可以手动创建 Dockerfile 或使用现有文件。
重要：Dockerfile 模板的前 N 行（N 由系统返回）是系统定义的，不能修改。只能修改第 N+1 行之后的内容，否则可能导致镜像构建失败。系统会在下载成功后显示不可编辑的行数，请务必遵守此限制。

image create - 创建镜像

从 Dockerfile 创建新的 AgentBay 镜像。

语法

agentbay image create <镜像名称> --dockerfile <路径> --imageId <基础镜像ID>

参数

<镜像名称>：自定义镜像名称（必需）。

选项

--dockerfile, -f <路径>：Dockerfile 文件路径（必需）。
--imageId, -i <ID>：基础镜像 ID（必需）。

示例

# 使用完整选项名称
agentbay image create my-app --dockerfile ./Dockerfile --imageId code-space-debian-12

# 使用短选项名称
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12

# 使用详细输出模式
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12 -v

输出示例

[BUILD] Creating image 'my-app'...
[STEP 1/4] Getting upload credentials... Done.
[STEP 2/4] Uploading Dockerfile... Done.
[STEP 3/4] Uploading ADD/COPY files (N files)... Done.
[STEP 4/4] Creating Docker image task... Done.
[STEP 5/5] Building image (Task ID: task-xxxxx)...
[STATUS] Build status: RUNNING
[SUCCESS] Image created successfully!
[RESULT] Image ID: imgc-xxxxx...xxx

构建流程

获取上传凭证。
上传 Dockerfile 到对象存储。
上传 ADD/COPY 引用文件（当 Dockerfile 中存在 COPY/ADD 时）。
创建 Docker 镜像构建任务。
启动镜像构建。

ADD/COPY 文件上传说明

创建镜像时，CLI 会解析 Dockerfile 中的 COPY 和 ADD 指令，并自动上传所引用的本地文件。路径相对于 Dockerfile 所在目录。支持单文件、多文件、子目录、通配符（如 *.py）；不支持绝对路径、路径穿越（如 ../）以及 ADD 的 URL 源。请确保 COPY/ADD 引用的文件均存在于 Dockerfile 所在目录或其子目录下。

说明

构建时间取决于镜像大小和复杂度。
使用 -v 选项可查看详细的构建日志。
构建过程中可以通过 image list 查看状态。
基础镜像 ID 必须是有效的系统镜像 ID，可通过 image list --system-only 查看。

image activate - 激活镜像

激活自定义镜像，使其可用于部署。

语法

agentbay image activate <镜像ID> [选项]

参数

<镜像ID>：要激活的镜像 ID（必需）。

选项

--cpu, -c <核心数>：CPU 核心数（2、4、8 或 16）。
--memory, -m <GB>：内存大小，单位 GB（4、8、16 或 32）。
--network-type：网络类型。ADVANCED 为高级网络，DEFAULT 为基础网络。不传时默认为基础网络。
--session-bandwidth：单 session 最高公网带宽，范围 2～200，单位 Mbps。选择高级网络时可选，非必传。不传表示不限制单 session 公网访问带宽上限。
--dns-address：DNS 服务器 IP 地址，选择高级网络时可选，非必传。可多次传入以配置多个 DNS 服务器。
--lifecycle-mode：释放模式。auto 为自动释放，manual 为手动释放。沙箱生命周期用于管理镜像实例的资源释放策略：auto 模式下系统会根据设定的条件自动释放资源，manual 模式下需手动停用。
--lifecycle-max-runtime：单次运行最长时长，单位分钟，非必传。设置该参数时，需 --lifecycle-mode 为 auto。
--lifecycle-hibernate：休眠最大时长，单位小时，非必传。设置该参数时，需 --lifecycle-mode 为 auto。
--lifecycle-idle-timeout：无活动最大时长，单位分钟，非必传。设置该参数时，需 --lifecycle-mode 为 auto。

支持的资源配置组合

2c4g：2 个 CPU 核心，4 GB 内存（未指定时的默认配置）。
4c8g：4 个 CPU 核心，8 GB 内存。
8c16g：8 个 CPU 核心，16 GB 内存。
16c32g：16 个 CPU 核心，32 GB 内存。

重要

激活镜像会分配计算资源并产生计费。按需使用并及时停用镜像，以避免不必要的费用。

示例

# 使用默认资源配置激活（默认 2c4g）
agentbay image activate imgc-xxxxx...xxx

# 使用 2c4g 配置激活
agentbay image activate imgc-xxxxx...xxx --cpu 2 --memory 4

# 使用 4c8g 配置激活
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8

# 使用 8c16g 配置激活
agentbay image activate imgc-xxxxx...xxx --cpu 8 --memory 16

# 使用 16c32g 配置激活
agentbay image activate imgc-xxxxx...xxx --cpu 16 --memory 32

# 使用详细输出
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8 -v

# 高级网络 - 最简形式
agentbay image activate imgc-xxxx --network-type ADVANCED

# 高级网络 - 带宽配置
agentbay image activate imgc-xxxx --network-type ADVANCED --session-bandwidth 10

# 高级网络 - 带 DNS 配置
agentbay image activate imgc-xxxx \
  --network-type ADVANCED \
  --dns-address 8.8.8.8 \
  --dns-address 8.8.4.4

# 高级网络 - 完整配置
agentbay image activate imgc-xxxx \
  --cpu 8 \
  --memory 16 \
  --network-type ADVANCED \
  --session-bandwidth 10 \
  --dns-address 8.8.8.8 \
  --dns-address 114.114.114.114

# 沙箱生命周期 - 手动释放
agentbay image activate imgc-xxxx --lifecycle-mode manual

# 沙箱生命周期 - 自动释放带单次运行最长时长
agentbay image activate imgc-xxx --lifecycle-mode auto --lifecycle-max-runtime 30

# 沙箱生命周期 - 完整配置
agentbay image activate imgc-xxxx \
  --lifecycle-mode auto \
  --lifecycle-max-runtime 50 \
  --lifecycle-hibernate 40 \
  --lifecycle-idle-timeout 30

输出示例

[ACTIVATE] Activating image...
Checking current image status... Done.
Creating resource group... Done.
Waiting for activation to complete...
  Status: Activating (elapsed: 5s, attempt: 2/60)
  Status: Activating (elapsed: 13s, attempt: 3/60)
[SUCCESS] Image activated successfully!

注意事项

只有自定义镜像可以激活。
系统镜像始终可用，无需激活。
CPU 和内存选项必须同时指定，且必须匹配支持的组合。
如果未指定 CPU 和内存，将使用默认资源配置（2c4g）。
激活过程通常需要 1～2 分钟。
如果镜像已经激活，命令会提示无需操作。
激活过程中会轮询镜像状态，轮询间隔动态调整（初始间隔较短，后续逐渐增大），最多尝试 60 次，总超时时间为 30 分钟。

image deactivate - 停用镜像

停用已激活的自定义镜像，释放相关资源。

语法

agentbay image deactivate <镜像ID>

参数

<镜像ID>：要停用的镜像 ID（必需）。

示例

# 停用镜像
agentbay image deactivate imgc-xxxxx...xxx

# 使用详细输出
agentbay image deactivate imgc-xxxxx...xxx -v

输出示例

[DEACTIVATE] Deactivating image...
Deleting resource group... Done.
Waiting for deactivation to complete...
  Status: Deactivating (elapsed: 5s, attempt: 2/40)
[SUCCESS] Image deactivated successfully!

注意事项

停用过程通常需要 1～2 分钟。停用过程中会轮询镜像状态，最多尝试 40 次，总超时时间约为 20 分钟。
停用完成后，可通过 agentbay image list 确认镜像已释放。
停用镜像后会释放相关计算资源，停止计费。

image delete - 删除镜像

永久删除自定义镜像。此操作不可逆，请谨慎使用。

前置条件

删除镜像前，需先执行 agentbay image deactivate <镜像ID> 停用镜像，确保相关资源已释放。

语法

agentbay image delete <镜像ID>

参数

<镜像ID>：要删除的镜像 ID（必需）。

示例

# 1. 先停用镜像（前置条件）
agentbay image deactivate imgc-xxxxxxxxxxxxxx

# 2. 交互式删除（会弹出确认提示 y/N）
agentbay image delete imgc-xxxxxxxxxxxxxx

# 3. 脚本/CI 中跳过确认直接删除
agentbay image delete imgc-xxxxxxxxxxxxxx --yes

# 4. 验证删除成功（镜像不再显示在列表中）
agentbay image list

输出示例

[DELETE] Deleting image 'imgc-0ab5ta4nzbwu9bvaa'...
Checking current image status... Done.
[INFO] GetMcpImageInfo Request ID: 3DFFDC7F-9EC2-10BA-878B-EE1E54D00245
[INFO] Image Type: User
[INFO] Current Status: Available (Deactivated)
Are you sure you want to permanently delete image 'imgc-0ab5ta4nzbwu9bvaa'? This action is irreversible. [y/N]: y
Deleting image... Done.
[INFO] DeleteMcpImage Request ID: 2EB74FE6-5757-167F-B71E-0C474ED0419B
[SUCCESS] Image 'imgc-0ab5ta4nzbwu9bvaa' has been permanently deleted.

警告

删除镜像是永久性操作，不可恢复。删除前请先执行 agentbay image deactivate <镜像ID> 停用镜像，确保相关资源已释放。

image status - 查看镜像状态

语法

agentbay image status <镜像ID>

参数

<镜像ID>：要查看状态的镜像 ID（必需）。

示例

agentbay image status imgc-xxxxx...xxx

状态说明

镜像状态分为构建状态和资源状态两类：

分类	状态值	说明
构建状态	IMAGE_CREATING	镜像正在创建中。
构建状态	IMAGE_CREATE_FAILED	镜像创建失败。
构建状态	IMAGE_AVAILABLE	镜像可用，可以激活。
资源状态	RESOURCE_DEPLOYING	资源正在部署中。
资源状态	RESOURCE_PUBLISHED	资源已发布，可以使用。
资源状态	RESOURCE_DELETING	资源正在删除中。
资源状态	RESOURCE_FAILED	资源部署失败。
资源状态	RESOURCE_CEASED	资源已停止。

网络包管理

网络包管理用于查看已分配的网络包信息，包括关联的办公网络和弹性公网 IP 地址。当前仅支持列出网络包操作。

network package list - 列出网络包

语法

agentbay network package list [选项]

选项

--biz-region-id <地域ID>：地域 ID（默认：cn-hangzhou）。

示例

# 列出网络包，默认杭州地域
agentbay network package list

# 查询其他地域的网络包
agentbay network package list --biz-region-id cn-shanghai

输出说明

命令输出包含以下列：

NETWORK PACKAGE ID：网络包唯一标识符。
OFFICE SITE ID：关联的办公网络 ID。
EIP ADDRESSES：绑定的弹性公网 IP（Elastic IP，EIP）地址。

注意事项

说明

默认查询 cn-hangzhou 区域，可通过 --biz-region-id 参数指定其他区域。
如果指定区域下没有网络包，会提示"No network packages found"。
使用 -v 选项可查看 Request ID 等调试信息。

API Key 管理

API Key 命令属于 Management Commands，使用前需先完成 agentbay login 登录。

apikey create - 创建 API Key

语法

agentbay apikey create --name <名称>

选项

--name <名称>：API Key 名称（必需）。

示例

agentbay apikey create --name "my-api-key"

输出示例

API Key created successfully.
  ID:      ak-xxxxxxxxxxxx
  Name:    my-api-key
  Created: 2025-01-15 10:30:00

验证

创建完成后，执行 agentbay apikey list 查看已创建的 API Key 列表。

apikey concurrency set - 设置并发限制

语法

agentbay apikey concurrency set --api-key-id <API Key ID> --concurrency <数量>

选项

--api-key-id <API Key ID>：API Key ID（必需）。
--concurrency <数量>：并发限制，必须大于等于 1（必需）。

示例

agentbay apikey concurrency set --api-key-id ak-xxxxx --concurrency 5

验证

设置完成后，可通过查看 API Key 详情确认并发限制是否已生效。

Skill 管理

Skill 命令属于 Management Commands，使用前需先完成 agentbay login 登录。用于将本地 Skill 上传到云端并管理已创建的 Skill。

skills - Skill 命令组

语法

agentbay skills <子命令> [参数] [选项]

子命令

push：推送本地 Skill（目录或 .zip）到云端。
show：根据 Skill ID 查看详情。

全局选项（与子命令共用）

--verbose, -v：详细输出（显示上传地址、上传大小、RequestId 等调试信息）。
--help：查看帮助。

skills push - 推送 Skill

将本地 Skill 推送到云端：获取上传凭证，上传 zip，调用服务端创建 Skill。参数可以是包含 SKILL.md 的 Skill 根目录或已打好的 .zip 文件。

语法

agentbay skills push <skill-dir>|<skill.zip>

参数

<skill-dir>：Skill 根目录路径。目录下必须存在 SKILL.md；CLI 会校验其中的必填元数据，再将整个目录打包为 zip 后上传。
<skill.zip>：zip 文件路径，原样上传。

SKILL.md 要求（目录模式）

须包含 name: 行，值为 Skill 名称（必填）。例如：name: my-skill。
可选包含 description: 行，作为描述。
建议使用 YAML 风格前置元数据：

---
name: my-skill
description: 可选描述
---

# Skill 正文

上传与命名

目录模式：zip 文件名为「目录基名 + .zip」。例如目录为 ./pdf，则上传文件名为 pdf.zip；基名为空或 . 时使用 skill.zip。
zip 模式：以上传的 zip 文件名为准。

执行流程

[STEP 1/3] 获取上传凭证（预签名 URL 等）。
[STEP 2/3] 上传：目录先打包再上传；zip 直接上传。
[STEP 3/3] 调用创建 Skill 接口；成功后打印 Skill ID。

示例

# 从包含 SKILL.md 的目录推送
agentbay skills push ./my-skill

# 推送已打包的 zip
agentbay skills push ./my-skill.zip

# 详细输出
agentbay skills push ./my-skill -v

输出示例

[STEP 1/3] Getting upload credential...
[STEP 2/3] Packing and uploading skill...
[STEP 3/3] Creating skill...

[SUCCESS] Skill created successfully!
[RESULT] Skill ID: <skill-id>

说明

路径必须是已存在的目录或扩展名为 .zip 的文件。
目录模式下若缺少 SKILL.md 或缺少 name:，命令会失败并给出修复提示。
zip 内条目使用 DEFLATE 压缩。

skills show - 查看 Skill 详情

根据 Skill ID 查询并打印 Skill 详细信息。

语法

agentbay skills show <skill-id>

参数

<skill-id>：Skill 唯一标识（skills push 成功后在 [RESULT] 中输出的 ID）。

输出说明

SkillId：服务端返回的 ID。
Name、Description：名称与描述。描述较长时会自动换行缩进显示。

示例

# 查看 Skill 详情
agentbay skills show <skill-id>

# 查看详细输出
agentbay skills show <skill-id> -v

认证管理

login - 登录

语法

agentbay login

登录流程

启动本地回调服务器。
打开浏览器进行阿里云认证。
接收授权码并交换访问令牌。
保存认证令牌到本地配置文件。

输出示例

Starting AgentBay authentication...
Starting local callback server on port 3001...
Opening browser for authentication...
Browser opened successfully!
Waiting for callback on http://localhost:3001/callback...
Authentication successful!
Received authorization code: xxxxx...
Exchanging authorization code for access token...
Saving authentication tokens...
Authentication tokens saved successfully!
You are now logged in to AgentBay!

故障排查

如果端口 3001 被占用，使用以下命令检查：

macOS/Linux：lsof -i :3001
Windows：netstat -ano | findstr :3001

logout - 登出

语法

agentbay logout

登出流程

尝试撤销服务器端的刷新令牌。
清除本地配置文件中的认证令牌。

输出示例

Logging out from AgentBay...
Revoking server tokens...
Refresh token revoked successfully
Clearing local authentication data...
Successfully logged out from AgentBay

说明

即使服务器端撤销失败，本地数据仍会被清除。
访问令牌是短期有效的，会自动过期。
撤销刷新令牌会同时使相关的访问令牌失效。

version - 版本信息

语法

agentbay version

输出示例

AgentBay CLI version 1.0.0
Git commit: abc1234
Build date: 2025-01-15
Environment: production
Endpoint: xiaoying-share.cn-shanghai.aliyuncs.com

输出字段

Version：CLI 版本号。
Git commit：构建时的 Git 提交哈希。
Build date：构建日期。
Environment：当前环境（production 或 prerelease）。
Endpoint：当前使用的 API 端点。

配置说明

配置文件结构

配置文件采用 JSON 格式，包含以下信息：

访问令牌（Access Token）。
刷新令牌（Refresh Token）。
ID 令牌（ID Token）。
令牌类型（Token Type）。
令牌过期时间（Expires At）。

令牌管理

CLI 自动管理令牌：

自动刷新：访问令牌过期前自动使用刷新令牌获取新令牌。
安全存储：令牌存储在用户配置目录，仅当前用户可访问。
令牌验证：每次 API 调用前检查令牌有效性。

环境变量

CLI 支持通过环境变量配置：

AGENTBAY_ENV：运行环境。可选值：prod（国内生产）、pre（国内预发布）、international（国际站）。
AGENTBAY_CLI_ENDPOINT：可选覆盖，用于自定义 API 端点。

常见问题

认证相关

Q：登录时提示端口被占用怎么办？

A：端口 3001 可能被其他程序占用。可以：

关闭占用端口的程序。
使用 lsof -i :3001（macOS/Linux）或 netstat -ano | findstr :3001（Windows）查找占用进程。
终止占用进程后重试。

Q：浏览器无法自动打开怎么办？

A：CLI 会显示认证 URL，手动复制到浏览器中打开。

Q：登录超时怎么办？

A：认证流程有 5 分钟超时限制。超时后重新运行 agentbay login。

Q：如何检查当前登录状态？

A：运行任意需要认证的命令（如 agentbay image list），未登录时会提示先登录。

镜像相关

Q：如何查看可用的基础镜像？

A：使用 agentbay image list --system-only 查看所有系统镜像。

Q：镜像构建失败怎么办？

A：请检查：

Dockerfile 语法是否正确。
基础镜像 ID 是否有效。
是否修改了 Dockerfile 中系统定义的前 N 行。
使用 -v 选项查看详细错误信息。
使用 agentbay image init -i <系统镜像ID> 下载模板参考（系统镜像 ID 可用 agentbay image list --system-only 查看）。

Q：Dockerfile 的哪些部分不能修改？

A：使用 agentbay image init 下载的 Dockerfile 模板中，前 N 行（N 由系统返回）是系统定义的，不能修改。命令成功后会显示不可编辑的行数：

[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.

只能修改第 N+1 行之后的内容。修改前 N 行可能导致镜像构建失败。

Q：如何查看镜像构建状态？

A：使用 agentbay image list 查看构建状态。如需查看完整的镜像和资源状态，使用 agentbay image status <镜像ID>。

Q：激活镜像需要多长时间？

A：通常需要 1～2 分钟，激活过程中会显示进度信息。

Q：可以同时激活多个镜像吗？

A：可以，每个镜像独立管理，互不影响。

Q：停用镜像后数据会丢失吗？

A：停用镜像会释放计算资源，但镜像本身不会删除，可以重新激活。

命令使用

Q：如何查看命令帮助？

A：使用 --help 或 -h 选项：

agentbay --help
agentbay image --help
agentbay image create --help

Q：如何启用详细日志？

A：在子命令中使用 -v 或 --verbose 选项：

agentbay -v image create my-app -f ./Dockerfile -i code-space-debian-12

Q：配置文件在哪里？

A：

macOS/Linux：~/.config/agentbay/config.json
Windows：%APPDATA%\agentbay\config.json

Q：如何重置配置？

A：删除配置文件后重新登录：

# macOS/Linux
rm ~/.config/agentbay/config.json

# Windows
del %APPDATA%\agentbay\config.json

错误处理

Q：遇到"Request ID"错误怎么办？

A：错误信息中会包含 Request ID，请记录此 ID 并联系技术支持。

Q：网络连接问题怎么办？

A：请检查：

网络连接是否正常。
防火墙设置是否阻止了连接。
是否能够访问 AgentBay 服务端点。

环境切换

概述

AgentBay CLI 支持在生产环境和预发布环境之间切换。此功能主要用于内部开发和测试。

环境说明

生产环境（production）：默认环境，用于正式使用。
预发布环境（prerelease）：用于测试和验证。
国际站环境（international）：使用国际站服务。

切换方法

临时切换（单次命令）

AGENTBAY_ENV=prerelease agentbay login

会话级切换（当前终端）

# macOS/Linux
export AGENTBAY_ENV=prerelease
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="prerelease"
agentbay login
agentbay image list

永久切换（添加到配置文件）

# macOS/Linux - 添加到 ~/.zshrc 或 ~/.bashrc
echo 'export AGENTBAY_ENV=prerelease' >> ~/.zshrc
source ~/.zshrc

# Windows - 添加到系统环境变量

切换回生产环境

# 取消环境变量
unset AGENTBAY_ENV

# 或显式设置为生产环境
export AGENTBAY_ENV=production

验证当前环境

使用 agentbay version 查看当前环境：

agentbay version

输出中的 Environment 字段显示当前环境。

使用国际站

如需使用国际站（海外区域），将环境设为 international 即可。

环境变量

AGENTBAY_ENV=international：使用国际站。
可选覆盖：AGENTBAY_CLI_ENDPOINT。

示例（当前终端生效）

# macOS/Linux
export AGENTBAY_ENV=international
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="international"
agentbay login
agentbay image list

设置后执行 agentbay version 可确认当前环境与端点。

支持的环境值

生产环境：production、prod 或不设置（默认）。
预发布环境：prerelease、pre、staging。
国际站：international。

注意事项

说明

不同环境的认证令牌是独立的，需要分别登录。
不同环境的镜像和资源是隔离的。
切换环境后需要重新登录。
此功能主要用于内部测试，普通用户应使用默认的生产环境。

技术支持

如遇到问题，请提供以下信息：

CLI 版本（agentbay version）。
错误信息（包括 Request ID）。
操作步骤。
系统信息（操作系统、版本）。

附录

资源配置参考

image activate 命令通过 --cpu 和 --memory 参数自定义资源配置。两个参数均接受整数值。

支持的 CPU 和内存组合：

CPU 核心数	内存（GB）	配置名称
2	4	2c4g（默认）
4	8	4c8g
8	16	8c16g
16	32	16c32g