CLI 参考
physiclaw CLI 是整个系统的唯一入口：它检查你的机器、运行 MCP 服务器、带你完成一次性设置，
并管理模型、技能和配置。任意命令加上 -h / --help 可查看其完整选项，physiclaw --version
可打印版本号。顶层命令是 doctor、server、status 和 uninstall；分组的子应用是
setup、config、models 和 skills。
doctor
Section titled “doctor”一次 只读 的健康检查——它从不改变任何东西。
physiclaw doctor它能感知服务器：如果有一个 PhysiClaw 服务器正在运行，doctor 会信任该服务器实时的 /api/status
（服务器已经占着串口和相机，重新探测要么会报告”忙”要么会把它弄坏）。当没有服务器在运行时，
doctor 会主动探测 GRBL 机械臂并枚举相机。任何东西不工作时，都先用它。
server
Section titled “server”运行 MCP 服务器——并且，除非另有指示，同时运行内置的 agent 运行时。
physiclaw server启动时它会打印 MCP 端点（http://localhost:8048/mcp）、手机桥接 URL 和一个二维码链接，
然后打开浏览器中的硬件设置向导。
| 选项 | 默认 | 作用 |
|---|---|---|
--port | 8048 | MCP 服务器端口 |
--host | 0.0.0.0 | 绑定地址 |
-v, --verbose | 关 | 详细的调试输出 |
--no-runtime | 关 | 不启动 agent 运行时循环（仅 MCP 服务器） |
--warm-start | 关 | 从已保存的校准包自动连接硬件并跳过 setup hardware；若校准包不完整则放行继续 |
--cam-index | 校准包中的值 | 为 --warm-start 覆盖相机索引 |
--no-setup-hardware | 关 | 启动时不自动打开浏览器设置向导 |
--save-tool-calls | 关 | 把每次 peek / screenshot 的输出转储到数据目录下 |
--save-snapshots | 关 | 转储每一帧原始相机画面 |
--save-screenshots | 关 | 转储手机自身的每一张原始截图 |
status
Section titled “status”一份快速概览快照——视觉模型、校准状态和 jobs 文件。与 doctor 不同，它 不会 探测硬件，
所以可以安全地管道传给 grep / jq。
physiclaw status一次性配置，包含以下子命令。
setup local-vision-model
Section titled “setup local-vision-model”下载并转换为 peek 和 screenshot 提供能力的 OmniParser 图标检测模型。
physiclaw setup local-vision-model转换所需的重量级依赖（约 500 MB 的 ultralytics + onnx）在一个一次性的 uv 环境中运行，
所以它们绝不会进入 PhysiClaw 的安装环境——uv 必须在你的 PATH 上。传入 --force 可在模型已存在时
仍强制重新下载。
setup hardware
Section titled “setup hardware”交互式的机械臂 + 相机校准向导。服务器必须已经在运行。
physiclaw setup hardware它走的步骤与浏览器向导编号相同——连接手机桥接、摆好设备、连接机械臂和相机、定位屏幕、 校准机械臂（18 个点击点）和相机（15 个圆点）、验证，以及核查 AssistiveTouch。
| 选项 | 作用 |
|---|---|
-a, --auto | 自动模式——跳过交互式提示 |
--trace | 运行可选的边缘描迹精度步骤 |
--server-url | 正在运行的服务器 URL（默认 $PHYSICLAW_SERVER 或 http://localhost:8048） |
config
Section titled “config”查看并编辑用户配置文件 ~/.physiclaw/config.toml。通过 set / unset 进行的编辑会保留你的注释和顺序。
| 命令 | 作用 |
|---|---|
physiclaw config path | 打印配置文件路径 |
physiclaw config show | 以 TOML 形式转储生效后的配置（API 密钥被遮蔽） |
physiclaw config get <section.key> | 读取一个键，例如 engine.max_turns |
physiclaw config set <section.key> <value> | 设置一个键（值会按类型强制转换） |
physiclaw config unset <section.key> | 把一个键还原为其内置默认值 |
physiclaw config edit | 在 $EDITOR 中打开文件（不存在时从模板创建） |
每个 section 的含义详见 配置。
models
Section titled “models”列出、查看并切换当前活动模型。模型是一个 provider/model 引用（例如
anthropic/claude-sonnet-4-6 或 qwen/qwen3.6-plus）；PhysiClaw 会从各 provider 的 API 实时发现
其模型列表，而不是内置一份精选清单。
| 命令 | 作用 |
|---|---|
physiclaw models | 显示当前活动引用、其来源，以及 provider 的密钥状态 |
physiclaw models list [provider] | 列出已发现的模型（来自本地缓存） |
physiclaw models use <provider/model> | 切换当前活动模型（精确引用；别名：set） |
physiclaw models key <provider> [value] | 设置某个 provider 的 API 密钥——省略 value 时以隐藏提示输入，随后拉取其实时模型列表 |
physiclaw models keys | 每个 provider 的密钥状态（env / config / 未设置），已遮蔽 |
physiclaw models discover <provider> | 重新拉取某个 provider 的实时模型列表 |
典型的首次运行是两条命令：
physiclaw models key anthropic # paste the key at the hidden promptphysiclaw models use anthropic/claude-sonnet-4-6skills
Section titled “skills”从一个 git 仓库源安装、列出并移除技能。技能源是一个带有顶层 skills/<name>/SKILL.md 的仓库；
安装会把那棵目录树复制到 ~/.physiclaw/skills/<name>/。
| 命令 | 作用 |
|---|---|
physiclaw skills install <name> --from <repo> | 克隆并安装一个技能（--ref 指定分支/标签，--force 覆盖） |
physiclaw skills list | 列出已安装的技能及其来源出处 |
physiclaw skills uninstall <name> | 移除一个技能（对用户自建的技能用 --force） |
--from 接受 owner/repo 简写、完整 git URL 或本地路径。用
physiclaw config set skills.default_source <repo> 设一个默认源，即可省去 --from 标志。
重启服务器以加载新安装的技能。
uninstall
Section titled “uninstall”移除 PhysiClaw 的用户数据。不带任何标志时，在删除任何东西前会先提示确认。
| 选项 | 作用 |
|---|---|
--data / --all | 移除整个 ~/.physiclaw 数据目录 |
--config | 仅移除配置文件（保留校准、记忆、模型） |
-y, --yes | 跳过确认提示 |
--dry-run | 打印将被移除的内容但不实际删除 |
CLI 二进制文件本身由安装它的工具移除——uv tool uninstall physiclaw——uninstall
会把这条命令作为最后的提醒打印出来。