AgentBay：AgentBay CLI使用手冊

主要功能

• 認證管理：基於 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
            

# 更新 Homebrew
brew update

# 清理緩衝
brew cleanup

# 重新安裝
brew reinstall agentbay
              

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

# 重新安裝
brew reinstall agentbay
              

# 修複 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. 建立自訂鏡像

agentbay image create myapp --dockerfile Dockerfile --imageId 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 的命令按功能分為以下章節，方便快速尋找：

鏡像啟用與停用說明

• 自訂鏡像：使用之前需要啟用，啟用後可用於部署。

• 系統鏡像：始終可用，無需啟用。

• 停用鏡像：使用完畢後停用自訂鏡像以節約資源，停用已啟用的自訂鏡像會釋放相關資源。

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 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.

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

構建流程

1. 擷取上傳憑證。

2. 上傳 Dockerfile 到Object Storage Service。

3. 上傳 ADD/COPY 引用檔案（當 Dockerfile 中存在 COPY/ADD 時）。

4. 建立 Docker 鏡像構建任務。

5. 啟動鏡像構建。

ADD/COPY 檔案上傳說明

建立鏡像時，CLI 會解析 Dockerfile 中的 COPY 和 ADD 指令，並自動上傳所引用的本地檔案。路徑相對於 Dockerfile 所在目錄。支援單檔案、多檔案、子目錄、萬用字元（如 *.py）；不支援絕對路徑、路徑穿越（如 ../）以及 ADD 的 URL 源。請確保 COPY/ADD 引用的檔案均存在於 Dockerfile 所在目錄或其子目錄下。

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.

image status - 查看鏡像狀態

文法

agentbay image status <鏡像ID>

參數

• <鏡像ID>：要查看狀態的鏡像 ID（必需）。

樣本

agentbay image status imgc-xxxxx...xxx

狀態說明

鏡像狀態分為構建狀態和資源狀態兩類：

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：關聯的辦公網路識別碼。

• EIP ADDRESSES：綁定的彈性公網 IP（Elastic IP，EIP）地址。

注意事項

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 詳情確認並發限制是否已生效。

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 檔案名稱為準。

執行流程

1. [STEP 1/3] 擷取上傳憑證（預簽名 URL 等）。

2. [STEP 2/3] 上傳：目錄先打包再上傳；zip 直接上傳。

3. [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>

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

登入流程

1. 啟動本地回調伺服器。

2. 開啟瀏覽器進行阿里雲認證。

3. 接收授權碼並交換存取權杖。

4. 儲存認證令牌到本地設定檔。

輸出樣本

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

登出流程

1. 嘗試撤銷伺服器端的重新整理權杖。

2. 清除本地設定檔中的認證令牌。

輸出樣本

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 可能被其他程式佔用。可以：

1. 關閉佔用連接埠的程式。

2. 使用 lsof -i :3001（macOS/Linux）或 netstat -ano | findstr :3001（Windows）尋找佔用進程。

3. 終止佔用進程後重試。

Q：瀏覽器無法自動開啟怎麼辦？

A：CLI 會顯示認證 URL，手動複製到瀏覽器中開啟。

Q：登入逾時怎麼辦？

A：認證流程有 5 分鐘逾時限制。逾時後重新運行 agentbay login。

Q：如何檢查當前登入狀態？

A：運行任意需要認證的命令（如 agentbay image list），未登入時會提示先登入。

鏡像相關

Q：如何查看可用的基礎鏡像？

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

Q：鏡像構建失敗怎麼辦？

A：請檢查：

1. Dockerfile 文法是否正確。

2. 基礎鏡像 ID 是否有效。

3. 是否修改了 Dockerfile 中系統定義的前 N 行。

4. 使用 -v 選項查看詳細錯誤資訊。

5. 使用 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：請檢查：

1. 網路連接是否正常。

2. 防火牆設定是否阻止了串連。

3. 是否能夠訪問 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。

注意事項

資源配置參考

image activate 命令通過 --cpu 和 --memory 參數自訂資源配置。兩個參數均接受整數值。

支援的 CPU 和記憶體組合：