常见问题（FAQ）

说明： 本页出现的 abx 命令由 cli 仓库中的 Node.js CLI 提供（npm install -g @agent-sandbox/cli）。CLI 专属文档（CLI 设计、教程、参考）也在该仓库；本仓库记录 Python SDK（agent-sandbox）与容器侧运行时（agent-sandbox-server）。

连接超时

症状

[E5001] Failed to connect to sandbox service
  Suggestion: Check network connectivity and firewall rules.

排查

1. 检查网络：确认可以访问 api.cn-hangzhou.e2b.fc.aliyuncs.com bash curl -I https://api.cn-hangzhou.e2b.fc.aliyuncs.com

2. 检查超时配置：增大 HTTP 超时 bash abx config set http_timeout 60

3. 检查代理：如果在代理环境中，确保 https_proxy 正确配置

4. 检查区域：确认区域设置正确 bash abx config get region

认证失败

E1001 — API Key 无效或缺失

[E1001] API key cannot be empty
  Suggestion: Check your ABX_SANDBOX_API_KEY environment variable or pass sandbox_api_key.

解决：

# 检查配置状态
abx config get sandbox_api_key

# 重新设置 API Key
abx config set sandbox_api_key your-api-key

# 或设置环境变量
export ABX_SANDBOX_API_KEY="your-api-key"

E1003 — AK/SK 凭证无效

[E1003] AccessKey ID and Secret cannot be empty

解决：确保同时设置了 AK ID 和 AK Secret：

export ALICLOUD_ACCESS_KEY_ID="your-ak-id"
export ALICLOUD_ACCESS_KEY_SECRET="your-ak-secret"

E1002 — Token 过期

[E1002] The SDK should auto-refresh tokens. If this persists, check system clock synchronization.

解决：检查系统时钟是否准确。SDK 会自动刷新 AK/SK 临时 token（有效期 3600 秒，到期前 300 秒刷新）。

模板不存在

E2001 — TemplateNotFoundError

[E2001] Template 'my-template' not found
  Suggestion: Run 'abx template list' to see available templates.

解决：

1. 检查模板名称拼写
2. 确认模板已安装： bash abx template install owner/repo
3. 使用默认模板测试： bash abx create --template base

E2009 — SandboxNotFoundError

[E2009] Sandbox 'sbx-xxxx' was not found.

对该 ID 调用 Sandbox.connect()、get_info()、set_timeout()、pause() 或 resume() 时，平台返回了 HTTP 404。

解决：检查 ID 拼写，运行 abx list 查看运行中的沙箱。已销毁或已过期的沙箱无法重新连接，请重新创建。对未知 ID 调用 kill() 仍保持幂等，不会抛出异常。

能力不支持（E3004）

症状

[E3004] Capability 'ports' is not supported by this sandbox template.
  Suggestion: Declare 'ports' in the template's capabilities list (template.yaml) or use a template that supports it.

解释

Agent Sandbox 使用能力模型控制沙箱功能。每个能力需要在模板中显式声明：

解决

如果需要使用 terminal 或 ports 能力，使用声明了该能力的模板，或创建自定义模板：

# template.yaml
name: my-web-template
capabilities:
  - shell
  - files
  - code
  - terminal
  - ports

Server 端能力组注意：Server 端有 8 个能力组。其中 TERMINAL 默认启用，仅 DEV_TOOLS 和 BROWSER 默认禁用（_DEFAULT_DISABLED = {DEV_TOOLS, BROWSER}）。客户端能力（capabilities 字段）和 Server 端能力组是不同层面的控制。

配额超限

E2002 — QuotaExceededError

[E2002] Sandbox quota has been exceeded
  Suggestion: Destroy idle sandboxes or request a quota increase.

解决：

# 查看运行中的沙箱
abx list --status running

# 销毁不需要的沙箱
abx kill sbx-xxxx

# 批量销毁
abx kill --all --yes

命令执行超时

E3001 — CommandTimeoutError

[E3001] Command execution timed out
  Suggestion: Increase the timeout parameter or check if the command is hanging.

解决：

# SDK 中增加超时
result = await sandbox.commands.run("long-command", timeout=300)

# CLI 中增加超时
abx exec sbx-xxxx "long-command" --timeout 300

构建与部署相关

构建、推送、部署的错误（E7xxx 错误码，以及 abx create / abx template init 缺少 LLM Key）由 abx CLI 抛出，不属于这个 SDK。见 CLI 的排障指南和构建与部署。

文件操作

E4001 — 文件未找到

# 先检查文件是否存在
exists = await sandbox.files.exists("/path/to/file")
if not exists:
    print("文件不存在")

# 列出目录内容
entries = await sandbox.files.list("/home/user")

E4002 — 权限被拒绝

检查文件权限。沙箱默认用户为 user，可在命令中指定 user 参数。

安装问题

pip install 失败

# 确保使用正确的包名
pip install agent-sandbox

# 如果遇到依赖冲突
pip install agent-sandbox --force-reinstall

Python SDK 未找到

确认 Python 的 bin 目录在 PATH 中：

python -m agent_sandbox --version
# 或
pip show agent-sandbox | grep Location

下一步

• 认证详解 — 认证配置
• 配置参考 — 所有配置项
• 错误码参考 — 完整错误码列表

相关：abx CLI

CLI 特有的问题（找不到 abx、abx deploy 没有 Dockerfile、部署步骤长时间无输出、无效的快捷方式目标、abx template init --adopt 确认提示）见 CLI 仓库：故障排查（CLI）。