ostool 使用
ostool 可以直接查询、连接和运行远程开发板。使用公网租赁平台时，客户端先通过普通用户账号完成浏览器授权，再在管理员分配的有效租赁范围内创建开发板会话。本文只说明直接使用 ostool 的流程；TGOSKits 对开发板命令的封装见板卡管理。
1. 安装与服务配置
使用租赁平台前，需要在本机安装 ostool，并把客户端指向平台的 HTTPS 地址。本文命令按 ostool 0.27.2 编写。
1.1 安装固定版本
先查看已有版本，再安装或更新到 0.27.2，最后重新检查。安装成功后，最后一条命令的输出应包含 ostool 0.27.2。
cargo install ostool@0.27.2
ostool --version
cargo install 会安装独立的 ostool 可执行文件。如果 shell 仍找到旧版本，检查 command -v ostool 指向的路径是否为 Cargo 的可执行文件目录。
1.2 配置公网服务
配置界面只提供 server 和可选的 port，不能修改认证模式。新建配置的认证模式默认为 disabled，因此还要手工把 auth_mode 改为 required。
ostool board config
可以先在 TUI 中把 server 设为 https://ostool.muxai.net:14321/，保存后再编辑 ~/.ostool/config.toml 补上认证模式；也可以跳过 TUI，直接编辑文件中的两个字段。最终配置应为以下内容，URL 已经包含端口，因此 port 字段可以省略。
[board]
server = "https://ostool.muxai.net:14321/"
auth_mode = "required"
公网服务必须使用 HTTPS。客户端通过系统信任库校验证书；遇到证书错误时，应检查系统时间和证书信任，不要改成 HTTP 或跳过校验。
2. 登录与凭据
ostool login 默认使用浏览器设备授权。客户端会显示授权地址和一组短期用户码，并等待浏览器确认；授权成功后才会保存登录凭据。用户不应把用户码、设备码或令牌复制到文档、截图和聊天中。
2.1 完成浏览器授权
配置完成后，在终端启动登录。管理员后台账号不能代替普通用户账号完成这一步。
ostool login
终端会打印授权网址和 Code。按下面的顺序操作，保留当前命令等待授权结果：
- 打开终端给出的授权网址。
- 使用平台普通用户的邮箱和密码登录。
- 核对页面与终端显示的用户码，然后确认授权。
- 返回终端，等待
Logged in successfully.。
设备码由客户端在后台换取凭据，用户码只用于浏览器确认。两者都有有效期；页面提示无效、过期或已经使用时，重新执行 ostool login，使用新一组授权信息。
授权成功后，OAuth access token 到期时 TokenManager 会使用刷新凭据自动续签。凭据优先保存在系统 credential store；系统不支持时，ostool 会给出警告并退回用户级凭据文件。配置文件中不要写 token，也不要在截图中展示凭据文件内容。
2.2 检查状态并退出
状态命令用于确认服务地址、认证模式和凭据类型。首次登录前通常会看到 auth_mode: Required 和 credential: none；浏览器授权成功后，credential 应为 OAuth，还可能显示过期时间和权限范围，但不会打印 token 本身。
ostool auth status
使用结束后可以退出 CLI 登录。退出会清除客户端保存的登录凭据，但不会结束管理员创建的租赁记录。
ostool logout
再次执行 ostool auth status 时，已保存的浏览器登录凭据应显示为 credential: none。如果后续还要连接公网开发板，需要重新执行 ostool login。
3. 租赁与开发板会话
登录只证明客户端取得了当前用户的身份凭据，不代表账号已经获得开发板。网页首页的“立即申请”目前不能创建租赁，管理员必须先在后台为该普通用户建立一条当前有效的租赁。这是当前租赁平台的部署行为，不是 ostool 对所有服务端的通用要求。
3.1 确认有效租约
平台创建会话时会检查当前用户、请求的 board_type、标签、租赁状态和有效期。注册账号、登录网页或看到首页的空闲开发板，都不能替代管理员创建的有效租赁。
取得租赁后，可以列出当前服务返回的开发板类型。后续命令中的 <开发板类型> 应使用这里显示的 board_type，不要填网页上的开发板 ID。
ostool board ls
如果列表中没有需要的类型，或创建会话时报“无对应开发板的租赁权限”，请管理员核对租赁用户、开发板型号、标签、状态和起止时间。有效租赁是准入权限，不等同于已经占用一块实体开发板。
3.2 连接串口
board connect 按 --board-type 请求一块匹配的开发板。分配成功后，终端会显示开发板型号、开发板 ID、会话 ID 和到期时间；开发板提供串口时，命令随后进入 ostool 串口终端。
ostool board connect --board-type <开发板类型>
退出方式取决于当前活动界面。界面是 ostool 串口终端且启用了退出序列时，使用 Ctrl+A，松开后再按 x；这种界面既可能来自直接运行的 ostool board connect，也可能出现在 cargo xtask board connect，以及由 ostool 承载的 U-Boot 或 HTTP Boot 终端中。该按键序列不适用于 QEMU 或任意其他命令行提示符，遇到其他界面时应按对应文档或当前提示退出。不要 强制结束管理开发板会话的进程，否则客户端可能来不及请求释放会话。
会话创建后，ostool 会自动发送保活请求。正常退出串口终端时，客户端会停止保活并尝试释放会话。释放会话不会删除或结束管理员维护的租赁。
3.3 构建并运行
项目已经配置构建文件和 .board.toml 时，可以让 ostool 构建产物、申请会话并按开发板启动配置运行。BoardRunArgs 的 --board-type 会覆盖 .board.toml 中的开发板型号。
ostool board run --board-type <开发板类型>
这条命令与 board connect 的用途不同：connect 只分配开发板并打开串口，适合手工调试；run 会准备运行产物，再按平台提供的启动方式部署和运行。运行期间，ostool 会自动维持并在退出时尝试释放会话。
4. TGOSKits 命令边界
TGOSKits 同时提供顶层开发板管理命令和面向操作系统的开发板命令。三类入口最终都可能使用 ostool 的开发板服务能力，但参数、构建责任和终端行为并不相同。
4.1 入口职责
选择入口时先看当前任务是直接使用独立客户端、管理开发板，还是构建并运行某个操作系统。下表中的命令不可只按名称互换。
| 入口 | 主要用途 | 是否负责构建和运行系统 |
|---|---|---|
ostool board ... | 独立客户端直接执行config、ls、connect 或 run；本文说明的是这条入口 | 只有ostool board run 按项目配置构建并运行 |
cargo xtask board ... | TGOSKits 顶层开发板管理，提供查询、配置和人工串口连接等仓库工作流 | 不负责某个操作系统的完整构建和部署 |
cargo xtask <os> board ... | 按 ArceOS、StarryOS 或 Axvisor 的任务工具流程构建、部署并运行系统 | 负责对应操作系统的完整开发板运行流程 |
cargo xtask board 是仓库侧的薄封装，参数和附加能力可能不同于独立 ostool CLI。例如仓库命令可以带任务工具自己的会话文件参数，因此不要把本文的完整命令行直接复制到 cargo xtask 后面。
4.2 选择入口
只需要验证账号、租赁或独立客户端连接时，使用本文的 ostool 命 令。进入 TGOSKits 工作区后，可以按任务目标选择仓库入口：
- 查看板型、编辑服务器配置或进行人工串口调试时，使用
cargo xtask board。 - 构建并在开发板上运行指定操作系统时，使用
cargo xtask <os> board，并按对应系统文档提供目标、分组或运行参数。 - 排查两类仓库命令的参数和配置优先级时，查阅板卡管理，不要根据独立
ostool的选项猜测任务工具行为。
如果命令已经进入某个任务工具管理的流程，应根据当前活动终端判断退出方式。只有 ostool 串口终端启用了退出序列时才使用 Ctrl+A 后按 x；QEMU 和其他提示符应按对应文档或界面提示操作。