OneBots 工作台

工作台是管理服务的终端客户端。它与 Web 共用安装、配置、网关启停和账号验证接口，不直接修改运行中的依赖，也不另起一套网关。

连接工作区

先确保管理服务已运行。前台部署可在一个终端运行：

onebots serve --data-dir /path/to/data

再从另一个交互式终端连接同一工作区：

onebots ui --data-dir /path/to/data

onebots tui 和交互式无参数启动进入同一个工作台。已安装系统托管时连接其原工作区，不要创建另一份目录。工作台无法连接管理服务时会报错，不会退回旧网关启动方式。

安装与配置

1. 选择“选择并安装依赖”，选择平台、输出协议和框架。空白安装不预选账号或协议。
2. 查看安装计划及必需 peer；私有包下载授权按提示隐藏输入，不写入配置。安装后先验证候选版本，安装成功不代表账号已启用。
3. 选择“配置账号与协议”，根据已安装扩展的 Schema 编辑配置草稿。
4. 校验草稿并明确应用。保存与应用不同；配置变更或版本冲突需要重新核对，不能覆盖未知的外部修改。
5. 查询状态，按需启动网关。停止网关不会关闭管理服务或 Web。

依赖选择始终表示下一运行版本的完整集合。取消已安装扩展的勾选时，工作台会明确列出移除项；如果适配器或协议仍被账号、出口或 plugins 引用，计划会被拒绝。先在配置管理中删除引用并应用，再创建候选。当前活动目录不会被原地删除，候选验证后仍需单独确认激活。相同流程也可从 onebots extensions install 和 onebots extensions remove 进入。

“升级网关运行版本”复用同一安装计划和版本切换流程，不代表管理服务自身已升级。详见运行版本升级。

账号登录验证

选择“账号登录验证”，按平台声明完成输入、短信或确认操作。所有答案隐藏输入；平台提供图片时可转到 Web 查看。工作台不会自动打开链接或自动发送短信。

提交前会显示操作编号，请保留它。结果不明时选择“查询验证回执”，输入原编号；网关停止后仍可查询。调用成功不代表账号已经上线。完整说明见账号登录验证。

查看日志

工作台可以按来源读取管理服务、网关和控制操作日志；命令行入口如下：

onebots control logs --data-dir /path/to/data --source manager
onebots control logs --data-dir /path/to/data --source gateway
onebots control logs --data-dir /path/to/data --source operation

Web 的三个日志页签在激活时建立 SSE 连接，切换到其他页签或离开页面时断开。历史查询最多返回最近 64 KiB；网关已停止或启动失败时，管理服务仍可提供已有日志。

日志可能包含平台凭据和消息，请先脱敏再分享。该入口不提供任意文件读取或清空日志；操作系统托管日志使用 onebots logs 查看。完整区别见诊断与常见故障。

浏览器授权

选择“授权新浏览器设备”，把一次性设备码填入 Web 配对页。授权码五分钟有效，新增设备不会挤掉已有设备。凭据丢失与撤销操作见管理端登录与恢复。

常见问题

情况	处理
工作台无法连接	检查管理服务是否运行，以及 --data-dir 是否与服务一致。
私有依赖安装失败	检查下载授权与包访问资格，查询原安装任务；不要把 Token 写进配置。
配置校验失败	保留草稿，按字段提示修正并重新校验。
配置被外部修改	重新读取配置并核对，不强制覆盖。
YAML 损坏	按管理端修复流程保留原文件，显式创建替代草稿；不要直接删数据目录。
安装、应用或验证结果未知	查询原操作，不换 ID 自动重试，也不删除操作记录解除保护。

快捷入口与 Docker

onebots ui --data-dir /path/to/data --setup
onebots ui --data-dir /path/to/data --configure

docker exec -it <容器名> onebots ui --data-dir /data

--setup 进入安装向导，--configure 进入配置草稿。旧 -c/--config、--force/--reset、--web 或系统服务范围参数不属于新工作台；迁移到管理服务工作区后使用 --data-dir。

Docker 使用同一安装与配置能力，无需先运行宿主脚本，也不会在容器里安装 systemd。保护私有模块授权的方式见Docker 私有扩展安装。

CLI、系统服务和日常维护命令集中在本地管理栏目。