安装 RoboAPI
从 PyPI 安装 RoboAPI，连接设备与模型服务，打开本地控制台。
RoboAPI 运行在连接机械臂、相机和夹爪的 Linux 控制电脑上。你可以在这台电脑操作，也可以从个人电脑打开本地控制台。已有 RoboAPI 环境请直接看版本与升级。
系统要求
- Linux x86-64，Python 3.10–3.12；新环境推荐 Python 3.12。
- 控制电脑与机器人通过有线网络连接，并能访问模型服务。
- 相机和夹爪已按硬件准备连接。
- Franka 还需 glibc 2.28 或更新版本，以及实时内核与调度权限。
在 Ubuntu 安装图像处理所需系统库：
sudo apt-get update
sudo apt-get install -y libgl1 libglib2.0-0启动账户需具备视频和串口访问权限，通常由 video、dialout 组提供；更改组后重新登录。
1. 创建 Python 环境
先按 uv 安装说明安装 uv，再创建独立环境：
mkdir -p ~/roboapi
cd ~/roboapi
uv venv --python 3.12
source .venv/bin/activate2. 从 PyPI 安装
按机器人选择一条命令：
| 机器人 | 安装命令 |
|---|---|
| UR5 CB3 | uv pip install 'roboapi[ur-cb3,gripper]==0.4.5' |
| UR5e / UR7e | uv pip install 'roboapi[gripper]==0.4.5' |
| FR3，系统 5.9+ | uv pip install 'roboapi[franka,gripper]==0.4.5' |
FR3 系统 5.6.0 与 Panda 需使用对应的 SDK 安装命令。每个 Python 环境只安装一种 Franka SDK。
安装后检查命令是否可用：
roboapi --help安装包已包含本地控制台，控制电脑无需 Node.js。UR5e / UR7e 首次安装还需构建原生控制运行时；Franka 先按 部署指南准备 Desk 与实时控制机，再通过下方初始化向导配置工具负载。FR3 5.6.0 和 Panda 在初始化之后导出并导入负载文件。
接入其他机器人时，先将适配器安装到同一 Python 环境，再运行初始化向导。开发流程见接入新硬件，接口约定见硬件适配接口。
从已下载的安装包安装
也可以从 PyPI 发布文件下载 wheel，按发布文件摘要核对后安装。例如，FR3 系统 5.9+ 使用：
uv pip install '/absolute/path/to/roboapi-0.4.5-py3-none-any.whl[franka,gripper]'将路径和安装选项替换为你的实际文件与机器人配置。安装依赖仍需要网络；仅下载 RoboAPI wheel 不包含完整的离线依赖。
3. 连接设备与模型
roboapi init向导依次选择机械臂、夹爪和相机，并填写各组件的地址或设备路径，再配置模型连接。已安装的外部适配器与内置组件一起显示。Franka 还需填写 Desk 凭据，并选择匹配的标准装配负载或填写整套附件的质量、质心与惯量；UR 的负载在 PolyScope 中配置。
| 模型设置 | 填写内容 |
|---|---|
| Base URL | 默认 https://api.pokebot.com/v1，也可填写兼容服务的地址 |
| 模型 | 输入 Key 并连接后，从服务返回的可用列表中选择适合当前机器人的模型 |
| API Key | 在开发者控制台创建的 API Key |
准备账户和调用配置的方法见账户与 API Key。向导会携带 Key 请求模型列表，需要控制电脑能访问模型服务。连接失败时，根据提示修正地址、Key 或网络后重试；获取列表成功后再选择模型。模型的展示名称不一定等于调用 ID，向导会保存所选模型的实际 ID。RoboAPI 自动管理任务会话和执行回执。
向导完成后，将配置保存到 ~/.config/roboapi/，凭据保存在仅当前账户可读写的独立文件中。初始化会查询模型列表，不连接硬件；查询列表本身不会创建任务会话。使用其他配置位置时，执行 roboapi init --config /path/to/config.yaml。
4. 打开本地控制台
roboapi http在控制电脑打开 http://127.0.0.1:8080/，检查相机画面和设备连接。自定义配置用 roboapi http -c /path/to/config.yaml。
从另一台电脑操作时，在那台电脑建立 SSH 转发，将 user@robot-host 替换为控制电脑的用户名与地址：
ssh -N -L 8080:127.0.0.1:8080 user@robot-host保持连接，打开 http://127.0.0.1:8080/。本地服务默认仅监听回环地址，没有独立账户登录；开发者控制台账户用于云端服务。
5. 标定并运行
- 在 设置 → 设备 → 坐标标定 完成 初始位置与 A/B/C 坐标标定。
- 采集 C 后，网页会让机械臂返回初始位置，保存标定并初始化机械臂和夹爪。保持运动区域畅通；UR e-Series 需按提示切换 Remote 模式。
- 按需完成方向试动，选择 完成 返回运行画面。
- 检查设置中的活动范围。默认以初始位置为中心，每个方向为 60 cm；超出范围的目标会被限制在边界，任务继续执行。启动前机械臂已在范围外时，先返回初始位置再运行。
- 在本地控制台输入任务，点击发送或按
Shift+Enter开始运行。
活动范围约束的是控制目标，不是物理围栏。再次启动时沿用已保存的标定，先进入预览，再选择 启用控制；启用不会自动回到初始位置。装配、初始位置或任务坐标轴改变后重新标定。
关闭浏览器不会停止后台任务。停止任务使用 Robot Stop，关闭服务使用运行终端中的 Ctrl+C。