服务网关

个人网关是三层架构里的中间一层：Personal Agent 宿主，拥有该主机上的 ~/.okbot，跑对话与工具，对外提供本机 HTTP API。桌面应用与 okbot serve 共用同一实现。同一数据根（默认 ~/.okbot）上只允许一个服务监听端口。

相对关系：

客户端 1 : N 网关 — 桌面客户端可保存多套网关并切换当前连接（同时只连一套）。
网关 1 : N 运行电脑 — 该网关再登记多台运行电脑（见远程电脑）。

网关部署并保持运行时，Personal Agent 可持续服务；任务可打到已登记的多台运行电脑。常开取决于网关是否在跑。

客户端与网关（1 : N）

本机默认：冷启动且尚无网关时，桌面应用自动拉起网关；若端口上已有 OkBot（例如 okbot serve），窗口以附着模式连上——关掉窗口后网关继续运行。
多套网关：在设置 → 客户端 → 网关列表添加地址与访问令牌，探测通过后保存；点「使用」切换当前网关。切换到本机网关等场景可能提示重启以应用。
客户端偏好（含网关列表）在本机；聊天、助手、记忆、运行电脑列表始终在当前网关主机的数据根（默认 ~/.okbot）。
桌面应用只自动附着默认数据根（~/.okbot）及其配置端口；自定义 --data-dir 实例需在网关列表里手动填写地址与令牌。

本机网关设置

设置 → 网关端 → 网关服务：

端口、局域网网关、提供 Web UI
网关令牌：可创建任意多个命名令牌。每项含名称、类型（用户 / 超管）、密钥，以及每日/总共消息限额与每日/总共 Token 限额（0 或留空 = 不限制）。可打开用量页查看该令牌对各助手 / 小队的聊天次数与 Token 消耗。
令牌字符集为 [A-Za-z0-9_-]。已有令牌会复用，不会在普通保存 / 附着时另造一串；设置里的「重新生成」是单独动作。
令牌等同于对该网关的访问权（聊天、批准工具、改人设 / 记忆 / 技能等，视角色而定），请妥善保管。

默认仅绑定 127.0.0.1（未开局域网时校验 Host）。鉴权：Authorization: Bearer <token> 或 X-OkBot-Token（GET /v1/health 除外）。没有面向公网的未加固入口；开局域网仍靠令牌。

okbot serve

无界面只开服务：

okbot serve

读取已保存的端口、绑定、令牌与 Web UI 开关；令牌已存在则复用。启动成功后打印地址与令牌。端口上已有 OkBot 时直接退出。Ctrl+C 停止。

多实例（自定义数据根）

同一台机器上可并行多个网关实例：--port 与 --data-dir 必须成对出现（或两个都不指定，使用默认 ~/.okbot + 默认端口，通常为 18765）。

okbot serve --port 19001 --data-dir ~/okbot-alt
okbot status --port 19001 --data-dir ~/okbot-alt
okbot stop --port 19001 --data-dir ~/okbot-alt

端口或数据目录锁已被占用时会拒绝启动。status / stop / restart 对自定义实例同样要求成对参数。

常用 CLI（另见 okbot help）：serve、status、stop、restart、config、token、data、version。

局域网与 Web UI

开启局域网网关后绑定 0.0.0.0，仍靠令牌鉴权。开启提供 Web UI 时托管与桌面相同的前端；浏览器打开打印出的地址并用令牌登录（勿把令牌长期放进 URL）。

HTTP API（摘要）

常见能力：向助手 / 小队发消息（可 SSE）、列表与工具审批、中止回合、POST /v1/rpc/:op（CRUD、记忆 / 技能等）、GET /v1/events（花名册与回合事件）。

curl -N -X POST "http://127.0.0.1:<port>/v1/bots/<botId>/messages"   -H "Authorization: Bearer $OKBOT_TOKEN"   -H "Accept: text/event-stream"   -H "Content-Type: application/json"   -d '{"text":"你好"}'

一键复制 curl 不把真令牌放进剪贴板，占位为 $OKBOT_TOKEN。

Docker / Kubernetes

无界面网关可用 Docker Compose 或 Helm 部署（不含桌面端）。说明见产品仓库 docs/install-docker-k8s.md，或从快速开始进入。

能力边界

附着窗口 / 浏览器网关可用：聊天、审批、记忆、技能、市场新建助手、立即压缩等。

附着 / 浏览器边界：按本机路径导入导出助手包、数据备份恢复，以及部分网关配置视令牌角色而定；语音转写在桌面应用中可用。用户令牌权限较窄；超管令牌可管理完整网关设置。