一、现象描述
只有实例状态为 RUNNING，才表示沙箱已启动成功。各中间状态含义如下：
·STARTING：启动过程仍在进行。
·STARTING_FAILED：实例在创建或初始化阶段失败。
·FAILED：实例曾经启动成功，但后续运行阶段出现异常。
排查前建议先记录以下信息：
·RequestId
·ToolId 或 ToolName
·InstanceId
·实例 Status
·实例 StopReason（如果返回）
·完整错误码和错误消息
·最近一次查询时间
注意：说明：
注意：启动相关接口的实例结构中包含 Status 和 StopReason 字段。部分环境可能额外返回 StatusReason 字段，建议一并记录。
二、可能原因
·启动请求缺少必要参数或参数值不合法，例如未提供 ToolId、ToolName、TemplateId，或 Timeout 格式错误。
·目标 Tool 不存在、不可用，或当前调用身份没有操作权限。
·当前账号可用实例配额不足，启动请求在接口阶段被拒绝。
·启动过程中镜像、网络、挂载、探针或白名单能力校验失败。
·启动请求已受理，但实例未能从 STARTING 推进到 RUNNING。
三、解决思路
先区分故障发生在“启动请求阶段”还是“实例状态推进阶段”，再决定排查路径：
1. 如果 StartSandboxInstance 或 agr instance create 直接失败，优先根据错误码定位参数、Tool、权限或配额问题。
2. 如果启动请求已返回 InstanceId，继续查询实例状态，确认实例最终是进入 RUNNING，还是停留在 STARTING、转为 STARTING_FAILED 或进入 FAILED。
3. CLI 中启动操作使用 agr instance create，查询操作使用 agr instance get 和 agr instance list。如果 CLI 无法满足排查需求，可使用 Cloud API StartSandboxInstance 和 DescribeSandboxInstanceList 作为补充入口。
四、步骤 1：检查 CLI 和云 API 凭证状态
agr status -o json
输出中 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 表示云 API 凭证是否已注入。任一字段为 false 时，CLI 无法查询实例状态，需先完成 agr init 或补齐环境变量。
五、步骤 2：通过 CLI 发起启动，或核对现有启动命令
agr instance create –tool-id <tool-id> –timeout 300 -o json
注意以下差异：
·CLI 使用 agr instance create 作为启动入口。
·CLI 的 –timeout 是秒级整数；Cloud API 的 Timeout 是 300s、10m、1h 格式的 duration 字符串，两者不要混用。
·如果命令直接失败，记录返回中的 Failure.Code、Failure.Message 和命令退出状态。
·如果命令成功，记录返回中的 InstanceId，继续执行步骤 3。
六、步骤 3：查询实例状态，判断启动是否完成
agr instance get <instance-id> -o json
按 Tool 聚合同类问题时，可补充执行：
agr instance list –tool-id <tool-id> -o json
agr instance list –status 支持 STARTING、RUNNING、FAILED、STOPPING、STOPPED 五个筛选值。排查 STARTING_FAILED 时，使用 agr instance get 查询具体实例，或先获取未筛选列表再做本地过滤。
根据查询结果判断下一步：
·RUNNING：启动成功，转到验证结果。
·STARTING：启动仍在进行，按业务容忍度轮询，避免毫秒级高频查询。
·STARTING_FAILED：启动未完成，继续执行步骤 4。
·FAILED：实例曾经启动成功但运行阶段异常，继续执行步骤 4。
如果启动时设置了 Timeout，超过该超时仍未进入 RUNNING，可视为异常。未显式设置时，以 Tool 默认超时或系统默认值判断。
七、步骤 4：对照错误码缩小范围
| 错误码 | 含义 | 处理建议 |
| MissingParameter | ToolId、ToolName、TemplateId 同时缺失，或缺少其他必填参数 | 补齐请求参数后重试 |
| InvalidParameter | 请求格式不合法 | 检查请求体结构、字段名和字段类型 |
| InvalidParameterValue.Timeout | Timeout 格式错误或超出允许范围 | Cloud API 使用 300s、10m、1h；CLI –timeout 使用秒级整数 |
| InvalidParameterValue.NetworkMode | 网络模式不合法或与 Tool 配置不匹配 | 检查实例级网络参数与目标 Tool 配置是否一致 |
| ResourceNotFound.SandboxTool | 目标 Tool 不存在 | 核对 ToolId / ToolName，确认 Tool 已创建 |
| ResourceUnavailable.SandboxTool | 目标 Tool 当前不可用 | 先排查 Tool 状态，再重新启动 Instance |
| ResourceNotFound.SystemImage | 实例级替换镜像未在允许范围内 | 调整镜像配置，或改用已允许的系统镜像 |
| AuthFailure.UnauthorizedOperation | 当前身份没有目标 Tool 的操作权限 | 检查账号身份和授权范围 |
| LimitExceeded.SandboxInstance | 实例配额超限 | 查询当前运行实例数，停止空闲实例或申请提升配额后重试 |
| FailedOperation.RequestInProgress | 相同 ClientToken 的请求仍在处理中 | 等待已有请求完成后再查结果，不要更换 ClientToken |
| FailedOperation.DuplicateRequest | 相同 ClientToken 的请求已提交过 | 查询已有 InstanceId 的结果，不要重复创建 |
| InternalError | 系统内部错误 | 保留 RequestId，稍后重试；持续出现时提交工单 |
| FailedOperation.InsufficientBalance（部分场景） | 余额不足导致启动被拒 | 记录 RequestId 和账号余额状态，提交工单确认 |
八、步骤 5：必要时回退到 Cloud API 入口，保留原始请求和响应
启动请求示例：
{ "Action": "StartSandboxInstance", "ToolId": "sdt-browser-demo", "Timeout": "10m", "ClientToken": "sandbox-instance-create-001"}
查询请求示例：
{ "Action": "DescribeSandboxInstanceList", "InstanceIds": [ "ins-6f4c9c3e" ]}
如果启动请求已返回 InstanceId 但后续查询结果不是 RUNNING，重点保留查询结果中的 Status、StopReason、UpdateTime 和 RequestId。
九、验证结果
修复后，完成以下核对：
·执行 agr instance get <instance-id> -o json，或调用 DescribeSandboxInstanceList 查询同一 InstanceId。
·确认实例状态为 RUNNING。
·如果查询结果返回 TimeoutSeconds 和 ExpiresAt，确认有效期与预期一致。
·如果通过相同 ClientToken 重试创建，先确认之前的请求没有已成功返回实例。
十、资源清理
·实例状态为 FAILED 时，可执行停止或删除：
agr instance delete <instance-id> -o json
或调用 StopSandboxInstance。
·实例状态为 STARTING_FAILED 时，是否需要手动清理取决于系统回收策略。建议先保留 InstanceId、RequestId、Status 和最近一次查询结果，再决定是否继续停止或删除。
·如果问题来自配额不足，清理空闲实例后再重试，比重复创建更有效。
十一、提交工单
多次重试后仍无法恢复时，提交工单 并附上以下信息：
·RequestId
·ToolId 或 ToolName
·InstanceId
·实例 Status
·实例 StopReason
·完整错误码和错误消息
·启动时间与最近一次查询时间