本地管理
OneBots 在本机由四部分组成：操作系统维护管理服务，管理服务维护网关进程，Web 和命令行作为管理客户端连接管理服务。平台账号和协议出口只运行在网关中；网关停止或配置失败时，管理服务仍应可以登录和诊断。
该用哪个入口
| 需要完成的事 | 推荐入口 | 说明 |
|---|---|---|
| 首次选择适配器、协议和框架 | TUI 或 Web | 查看完整依赖计划，输入一次性私有仓库授权，验证后再激活 |
| 配置账号和协议出口 | Web；无浏览器时用 TUI | 两者共用配置草稿、校验和应用接口 |
| 日常启停网关、处理登录验证 | Web 或 TUI | 不会停止管理服务 |
| 执行本机维护命令 | Web 本地终端 | 只允许本机访问；每个连接使用独立 PTY，离开页面即终止 |
| 脚本化查询和部署 | CLI | 使用 --json 或 onebots control；外部操作保留任务 ID |
| 安装、启停或卸载系统托管 | CLI | 管理的是管理服务；系统级操作使用 --system |
| 查看界面之外的实现和配置项 | 文档站 | 文档用于操作说明，不代替运行状态和 Schema |
推荐阅读顺序
- 首次安装与工作台：创建工作区，启动管理服务，完成扩展和业务配置。
- 系统服务：让管理服务随系统启动，并区分用户级和系统级服务。
- CLI 命令索引：查询状态、管理扩展、控制网关和自动化操作。
- 备份、升级与恢复：升级前备份，遇到未知结果时对账或回退。
- 诊断与常见故障：按错误边界定位管理服务、网关、配置和依赖问题。
两条生命周期
管理服务和网关是两条独立生命周期：
text
onebots start / stop / restart
└─ 操作系统中的管理服务
onebots control start / stop / restart
└─ 管理服务托管的网关进程停止网关不会关闭 Web。停止管理服务会同时失去 Web、TUI、本地控制接口和网关托管能力。日常改配置、升级扩展或排查账号时，通常只需要控制网关。
工作区是管理边界
始终对同一个 --data-dir 操作。不要用另一份目录启动第二个管理服务，也不要直接修改活动运行版本下的依赖。配置、设备授权、数据库、日志、运行版本引用和操作记录都属于工作区。
Web 本地终端
Web 本地终端只在浏览器通过 localhost、127.0.0.1 或 [::1] 直接访问管理服务时可用。已登录的设备会话先签发 30 秒有效的单次连接票据；每个 WebSocket 连接独占一个 PTY。切换到其他页面、关闭页签或连接断开时，管理服务立即终止该 PTY。
终端中的 shell 拥有管理服务所在 OS 用户的权限，可以读取和修改该用户能够访问的文件。它不能通过远程地址或反向代理使用，也不应通过端口转发绕过本机限制。不要把管理服务管理端口暴露到公网。Web 本地终端使用 @karinjs/node-pty，需要 Node.js 24；使用其他 Node 版本或原生组件安装失败时，管理服务仍会启动，只禁用本地终端。此时运行 onebots doctor，按诊断修复当前安装，不要把普通命令执行接口作为替代。
Docker 使用相同的管理服务与网关边界，但容器内不安装 systemd、launchd 或 Windows 服务。见 Docker 部署。