E2B SDK 接入參數說明 - Function Compute

雲沙箱資料面以相容 E2B SDK 和 E2B CLI 為主，未提供獨立的資料面 SDK。開發人員接入資料面時，應繼續使用 E2B SDK / CLI 的對象、方法和參數命名，只把鑒權和服務端點切換到雲沙箱。Team、API Key、Quota 等資源管理能力屬於控制面，可通過原生 OpenAPI、阿里雲 SDK 或阿里雲 CLI 調用，詳情參見阿里雲 SDK & API 說明。

本文不替代 E2B SDK 官方類型定義。不同語言 SDK 的參數命名、預設值和單位可能不同，業務代碼應以所使用 SDK 版本的類型定義為準；本文只說明接入雲沙箱時必須關注的參數和相容邊界。

基礎配置

使用 E2B SDK 或 E2B CLI 接入雲沙箱時，至少需要配置 API Key、API URL 和網域名稱。

export E2B_API_KEY="<YOUR-API-KEY>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

其中 <region> 需要與雲沙箱所在地區一致。當前支援的 <region> 包括 cn-beijing、cn-shanghai、cn-hangzhou、cn-shenzhen、cn-hongkong、ap-southeast-1、us-east-1 和 us-west-1。如果 API URL、網域名稱、模板和 Sandbox 不在同一地區，常見結果是建立失敗、串連失敗或模板不可見。

API Key 應在Function Compute控制台建立和管理，具體步驟參見建立 API Key。不要通過 E2B SDK 管理雲沙箱 API Key，也不要把 API Key 寫入代碼倉庫、日誌、截圖或前端頁面。

E2B CLI 配置

新版本 E2B CLI 使用 E2B_API_KEY 認證。E2B_ACCESS_TOKEN 是 E2B 已廢棄的舊認證變數，不建議在新接入流程中使用。

如果 SDK 可以訪問雲沙箱，但 CLI 認證失敗，優先檢查 CLI 版本、E2B_API_KEY、E2B_API_URL 和 E2B_DOMAIN。

Python

Python SDK 通常使用 snake_case 參數名：

api_key：雲沙箱 API Key，對應 E2B_API_KEY。
api_url：雲沙箱 API URL，對應 E2B_API_URL。
domain：Sandbox 網域名稱尾碼，對應 E2B_DOMAIN。
template：建立 Sandbox 使用的模板名稱或模板 ID。
timeout：Sandbox 逾時時間。不同版本的 Python SDK 對單位和預設值的定義可能不同，使用前應確認當前 SDK 版本的類型定義。
envs：建立 Sandbox 時注入的環境變數。
metadata：寫入控制面的自訂中繼資料，適合儲存任務 ID、業務來源、Agent 類型等可索引資訊。

樣本：

import os
from e2b_code_interpreter import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter-v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    metadata={"task_id": "task-001"},
    envs={"TASK_ID": "task-001"},
)

try:
    result = sandbox.commands.run("python3 -c \"print('hello from sandbox')\"")
    print(result.stdout.strip())
finally:
    sandbox.kill()

TypeScript

TypeScript SDK 通常使用 camelCase 參數名：

apiKey：雲沙箱 API Key，對應 E2B_API_KEY。
apiUrl：雲沙箱 API URL，對應 E2B_API_URL。
domain：Sandbox 網域名稱尾碼，對應 E2B_DOMAIN。
template：建立 Sandbox 使用的模板名稱或模板 ID。部分調用方式會把模板作為 Sandbox.create() 的第一個參數傳入。
timeoutMs：Sandbox 逾時時間，通常以毫秒為單位。
envs：建立 Sandbox 時注入的環境變數。
metadata：寫入控制面的自訂中繼資料。

樣本：

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 10 * 60 * 1000,
  metadata: { task_id: "task-001" },
  envs: { TASK_ID: "task-001" },
});

try {
  const result = await sandbox.commands.run("python3 -c \"print('hello from sandbox')\"");
  console.log(result.stdout.trim());
} finally {
  await sandbox.kill();
}

參數使用建議

優先通過環境變數傳入 apiKey / api_key、apiUrl / api_url 和 domain，避免在代碼中寫入程式碼地區和憑證。
metadata 用於控制面查詢、審計和業務關聯，不會自動進入 Sandbox 運行環境。
envs 用於 Sandbox 內進程讀取，不應儲存需要長期持久化的業務狀態。
逾時時間要按任務實際運行時間長度設定。過短會導致任務中斷，過長會增加資源佔用和費用風險。
任務完成後應主動調用 sandbox.kill()。僅已開通白名單的帳號可在需要保留現場時使用暫停與恢複，不要把暫停當成預設的資源釋放方式。
遷移已有 E2B 應用時，先只替換 API Key、API URL 和網域名稱；確認最小建立、命令執行、檔案讀寫和資源釋放鏈路通過後，再接入模板、Code Interpreter、中繼資料和環境變數等能力。

不作為接入參數的能力

以下能力當前不應寫入雲沙箱的預設 SDK 接入路徑：

雲沙箱 API Key / Access Token 管理：通過Function Compute控制台完成，不通過 E2B SDK 管理。
Snapshot：已支援，但不屬於預設 SDK 接入路徑，使用說明參見快照（Snapshot）（邀測）。
Volume、Team 管理：當前不屬於雲沙箱 E2B 相容主路徑。
Metrics、Logs、Network Config Update：當前屬於受限能力，不適合作為生產監控、日誌採集或網路變更的控制面依賴。

完整能力邊界參見E2B SDK 相容 API 清單和開始使用 / E2B 相容說明。