常见问题
按现象查找解决方法，恢复设备连接和任务运行。
本地控制台打不开
在控制电脑激活安装环境，运行 roboapi http。默认地址为 http://127.0.0.1:8080/；从另一台电脑访问时，按 安装指南 建立 SSH 转发。
若找不到配置，先执行 roboapi init。自定义配置使用 roboapi http -c /path/to/config.yaml。UR e-Series 提示缺少原生程序时，在同一环境完成 UR 运行时安装。
适配器没有出现在初始化向导中
将适配器安装到运行 RoboAPI 的同一 Python 环境，再重新启动程序。检查向导输出的加载错误，并安装适配器声明的 SDK 依赖；同一组件组的名称不能与已有组件冲突。配置已选择但无法加载的组件会直接报错。注册与配置方法见硬件适配接口。
升级后提示缺少安装信息或工具负载
停止服务，在原环境运行 roboapi init --complete。自定义配置加上 -c /path/to/config.yaml。Franka 选择匹配的标准装配或填写自定义负载；URCap 填写实际控制器地址。若提示连接身份改变，重新标定后再启用控制。完整流程见版本与升级。
相机没有画面
先区分浏览器预览中断与控制电脑未获取到图像。页面会尝试恢复中断的预览；若设备状态仍有新帧，可重新打开页面。若设备也显示相机不可用：
- 确认相机已切换为 USB 视频模式，线缆支持数据传输。
- 检查采集设备路径与权限，确认未被其他程序占用。
- 确认相机支持 MJPG 1280×720、30 FPS。
v4l2-ctl --list-devices
ls -l /dev/v4l/by-id/将实际视频采集节点填入 camera.device。画面恢复后，已停止的任务需要重新发送。
如果只是边缘被裁切，选择 完整视野；如果隐藏了画面，点击相机图标恢复。浏览器中的裁切和隐藏不影响模型图像与录像。
有画面但不能发送任务
在 设置 → 设备 确认标定已保存、控制已启用、机械臂和夹爪已连接，再检查模型连接。已有标定的工位在重新启动后仍需启用控制。
如果提示机械臂在工作空间外，先返回 初始位置。Agent 发起的运行须先停止，才能从网页开始。完整操作见 本地控制台。
标定无法返回或完成
确认 A/B/C 在同一水平面且不共线，Home 位于平面上方，采样时保持相同工具朝向与接触点。
- UR e-Series：自动返回前切换到 Remote。
- Franka：释放其他 Desk 控制者，并按 部署指南 配置实时主机与末端工具。
- 返回失败：采样点保留；处理提示后选择 重试。
- 保存后启用控制失败：标定已经保留，只需处理提示并重新启用控制。
需要重新取最近一点时，点击 上一步；这不会移动机械臂。关闭窗口可稍后继续，断开设备才会丢弃未完成的示教。见 坐标标定。
方向试动停止后没有返回
这是停止操作的预期结果：停止会取消剩余轨迹，包括回程。先使用试动面板的返回操作，再尝试下一方向。每次试动从 Home 开始，会平移 5 cm、旋转 30°；不是只播放示意动画。
机器人到达边界后继续运行
默认活动范围为 Home 各轴正负方向 60 cm。超出范围的目标收敛到边界，策略仍在运行；需要结束任务时点击 停止。可以在空闲且结束标定后，通过 设置 → 设备 → 活动范围 调整范围。
活动范围限制目标的法兰中心位置，不约束整个机械臂或旋转，也不代替避障。详情见 活动范围。
模型连接失败
| 现象 | 处理 |
|---|---|
| 401 / 403 | 检查 API Key 是否有效，以及该 Key 的模型访问权限。 |
| 模型列表为空 | 确认 Key 在当前服务拥有模型访问权限，修正后重新点击 连接。 |
| 找不到原模型 | 检查是否使用正确的地址和 Key，再从重新获取的列表中选择可用模型。 |
| 无法连接 | 确认 Base URL 为正式服务地址 https://api.pokebot.com/v1，再从控制电脑检查网络、DNS 与代理设置。 |
invalid_response | 核对服务是否满足 本地运行协议，包括会话、执行回执与动作格式。 |
初始化也需要联网获取模型列表；连接失败时按向导提示重试。在控制台修改地址或 Key 后，先重新 连接，选择模型，再 保存。连接或保存失败会保留已保存的配置。
运行中的推理失败会结束本次运行。请求超时后先确认机器人与请求状态，再决定是否重新开始。
新指令没有开始执行
输入或选中预设只会更新草稿。点击发送或按 Shift+Enter 才会运行；Enter 是换行。
网页运行中发送非空草稿时，会先停止当前运行，再开始新任务。通过 HTTP 或 MCP 更新活动指令，则在下一轮推理生效，不打断当前动作块。需要立即停止使用 停止。
录像无法下载或任务无法删除
任务停止后，录像可能仍在保存。等待保存完成，再回看或下载。正在运行或保存录像的任务不能删除；批量清理会跳过这些任务。
清理录像保留指令、评价和备注；删除任务会一并移除这些记录。存储属于控制电脑，切换浏览器不会腾出该电脑的磁盘空间。
清除历史错误后设备仍未恢复
HTTP 的清除历史错误只删除日志中的历史错误记录与停止原因，不执行设备恢复。
先按当前故障处理连接、控制权或机器人状态，需要恢复设备时使用 恢复并返回初始位置；此操作会移动机械臂。初始位置也会移动机械臂并打开夹爪。
需要协助时，提供版本、发生时间、入口、错误码与请求编号。不要附 API Key 或 Desk 密码。见 本地运行错误 或 云端 HTTP 错误。