本地运行错误

本页覆盖本地控制台、HTTP API 和 MCP 工具。云端请求的 HTTP 状态与处理方式见云端错误。

读取错误

已知运行条件通过 MCP 返回结构化结果：

{
  "ok": false,
  "error": "calibration_required",
  "hint": "open Devices > Calibrate in the web interface, confirm safety and finish coordinate calibration",
  "detail": "..."
}

字段	含义
`error`	供程序判断的错误标识。
`hint`	建议的下一步操作。
`detail`	具体设备或运行条件。

本地 HTTP 通常返回 {"error":"原因"}，控制前置条件不满足时可附 kind: "control_not_ready"。其他 MCP 异常可能以 ToolError 返回。

运行条件

error	原因	处理
`not_alive`	相机、机械臂或夹爪不可用。	检查连接、视频帧是否更新与当前设备故障。
`control_not_ready`	控制模式、设备控制权或运动前置条件不满足。	按 detail 切换 UR Remote、释放 Desk 控制权或启用控制；若在活动范围外，先返回 Home。方向试动也须先回 Home。
`loop_running`	操作与当前运行状态或来源冲突。	读取状态，切换入口或修改设置前先停止。
`calibration_required`	缺少有效工位标定。	完成坐标标定，再启用控制。
`calibration_action_failed`	采点、返回或标定步骤失败。	按页面提示处理；返回失败保留采样点，保存后的启用失败保留标定。
`policy_unavailable`	模型发现、会话操作或推理失败。	检查 Base URL、模型 ID、Key 与下方的模型错误。

模型连接错误

运行记录中的 error_kind 提供更具体的分类：

error_kind	处理
`connect_timeout`、`transport_error`	检查控制电脑到服务的网络、地址与 TLS。
`read_timeout`	保留请求编号，确认请求与机器人当前状态后再决定是否重试。
`authentication_rejected`	使用有效的 API Key。
`not_authorized`	检查 Key 是否具备所选模型权限。
`model_unavailable`	选择同一服务 `/models` 返回的模型 ID。
`http_error`	按 HTTP 状态查阅模型服务的错误说明。
`invalid_response`	核对连续任务与会话中的会话和响应格式。
`policy_unavailable`、`runtime_error`	查看本地控制台与启动终端的具体原因。

推理失败会结束运行，不自动重复推理。超时后先确认设备与请求状态，避免重复执行动作。

恢复操作

**停止（Robot Stop）**中断受控运动。
**初始位置（Home）**打开夹爪并返回标定位置；恢复并返回初始位置先恢复设备再返回，两者均会运动。
HTTP /api/errors/clear 在空闲且设备可用时删除历史错误事件和停止原因，不恢复硬件。

请求失败后先读取当前状态再决定下一步。方向试动被停止后不会自动回程，应显式返回 Home 后再试。详情见常见问题。

需要协助时，提供版本、时间、操作入口、错误码与请求编号。运行日志默认位于 ~/.config/roboapi/logs/。不要提交 API Key、Desk 密码或敏感图像。

读取错误复制标题链接

运行条件复制标题链接

模型连接错误复制标题链接

恢复操作复制标题链接

本页内容

读取错误

运行条件

模型连接错误

恢复操作