Rovai AI

登录与日常维护

找到对应凭据，保持主机运行，并在重启或更新时保留工作台。

Token、浏览器会话与实例

登录 Token
实例的 Owner 凭据，只填写在对应实例的登录页。Desktop 从远程连接获取；Server 从启动终端或相同数据目录的 token 命令获取。
浏览器会话
登录后建立对应来源的浏览器会话。换浏览器、换来源或会话过期时可能需要重新登录；它与智能体认证无关。
Server 重启
Server 0.4.1 把认证状态保存在数据目录。继续使用原根目录；换目录意味着另一个实例和凭据。浏览器会话仍可能到期。
Desktop 重启
App 重启后需要重新开启 Desktop Web。从正在运行的 Desktop 获取当前 Token，不要假定以前保存的凭据仍有效。
权限范围
当前发布版是单 Owner 实例，不要把 Token 当成某个项目的受限邀请。HTTPS 或 Tailscale 保护连接，不提供独立用户角色。

查看路径与 Token · 使用同一数据目录

rovai-server --data-dir "$HOME/.rovai-server" paths
rovai-server --data-dir "$HOME/.rovai-server" token

私下保管凭据

macOS 0.4.0 使用安装页的 current/rovai-server 完整路径。paths 显示位置，token 输出秘密凭据；不要把输出贴入 Issue、截图或共享终端录屏。

Server 0.4.1 没有公开的 rotate-token 命令。凭据泄露时先关闭可达入口，再按该版本寻求恢复指导；不要删除数据库或尝试虚构参数。

浏览器连接状态不等于任务状态

关闭标签页、Wi-Fi 断开或代理重启可能只中断画面，已接收请求仍在主机上继续。重新连接同一实例、同一会话，查看执行、待审批事项和文件，再决定是否重复请求。

停止 Server、退出 Desktop、关机或休眠会影响执行主机。停止进程不会回滚已经写入的文件。重启后结合记录结果与当前文件，只发尚未完成的工作。

前台运行与再次启动

  1. 保持运行 Server 的终端打开。关闭终端可能结束进程；关闭浏览器没有同样作用。
  2. 需要停机时，先在 Rovai 完成或停止正在处理的工作，再在 Server 终端按 Ctrl-C 并等待退出。
  3. 使用相同版本程序、账号、数据根目录和网络参数重开。修改 --public-origin 后，应打开对应浏览器地址。
  4. 不要让第二个进程使用同一数据根目录。锁拒绝表示另一个实例仍持有目录，应查找进程，不要删除锁文件。

后台启动由系统管理器配置

安装器不建立系统服务。确定一个进程归属账号和一种启动方式。服务管理器环境不是交互 shell，应显式设置包含智能体程序的 PATH，并保留它的主目录与认证环境。

以下 Linux 示例假设普通账号叫 rovai，默认程序位于 /home/rovai，数据根目录为 /home/rovai/.rovai-server。先选择或创建该账号，并以它安装和登录；所有路径要一致替换。

Restart=no 避免启动失败后反复拉起进程；systemctl enable 设置开机启动，不代表中断请求会自动完成。主机网络与智能体依赖仍需可用。

Linux · /etc/systemd/system/rovai-server.service

[Unit]
Description=Rovai Server
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=rovai
WorkingDirectory=/home/rovai
Environment=HOME=/home/rovai
Environment=PATH=/home/rovai/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/rovai/.local/share/rovai-server/current/rovai-server --data-dir /home/rovai/.rovai-server --listen 127.0.0.1:8767
KillMode=control-group
TimeoutStopSec=90
Restart=no

[Install]
WantedBy=multi-user.target

补上所选连接方式的参数

模板仅监听回环。Serve / Caddy 在 ExecStart 末尾添加准确的 --public-origin https://…；可信局域网按相应教程替换 --listen 并添加 --allow-insecure-lan。不要再以前台启动同数据目录的第二个实例。

替换示例账号和路径后保存 unit。下方命令检查、启动并设置开机启动；日志仍保存在数据目录，journalctl 还可查看服务层错误。

Linux · 启动并检查

sudo systemd-analyze verify /etc/systemd/system/rovai-server.service
sudo systemctl daemon-reload
sudo systemctl enable --now rovai-server
sudo systemctl status rovai-server --no-pager
sudo journalctl -u rovai-server -n 50 --no-pager

Linux · 停止并取消开机启动

sudo systemctl stop rovai-server
sudo systemctl disable rovai-server

macOS · 账号登录后启动

  1. 使用用户级 LaunchAgent，不要以为安装器已经建立守护进程。下载下方 plist，把所有 /Users/rovai 替换为自己的绝对主目录，包括程序、数据、PATH 与日志路径。
  2. 加载前创建日志目录，将修改后的文件保存为 ~/Library/LaunchAgents/dev.rovai.server.plist。需要公共来源时，在 ProgramArguments 中把 --public-origin 和值分别添加为两个条目。
  3. 先停止前台实例。用 plutil -lint 检查，再通过 launchctl bootstrap gui/$(id -u) 和 plist 绝对路径加载。
  4. 本例 RunAtLoad 在该用户登录后启动，不是登录前启动；KeepAlive 为 false，不会持续重试失败进程。使用同一 domain 和 plist 的 launchctl bootout 停止并卸载，启动错误查看已配置日志。

macOS · 加载修改后的配置

mkdir -p "$HOME/.rovai-server/logs"
plutil -lint "$HOME/Library/LaunchAgents/dev.rovai.server.plist"
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/dev.rovai.server.plist"

macOS · 停止并卸载

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/dev.rovai.server.plist"

Windows · 登录后启动任务

  1. 任务计划程序是可选系统配置，不是 Rovai 安装器功能。用安装并登录智能体的同一个普通账号创建任务，先选择“仅当用户登录时运行”，不要默认勾选最高权限。
  2. 触发器选择“登录时”。程序填写绝对 …\Programs\RovaiServer\current\rovai-server.exe 路径；参数使用 --data-dir "C:\Users\rovai\.rovai-server" --listen 127.0.0.1:8767，替换账号并增加连接所需参数。
  3. “起始于”填写该账号主目录。常驻任务不要设置任意运行时限；重叠选择“不启动新实例”，并检查电源条件，避免电池供电时悄悄停止进程。
  4. 先运行一次，检查任务结果和 Server 日志。此方式在登录后启动，不是登录前 Windows 服务。需要正常停止时先完成工作，有运行控制台时使用 Ctrl-C；任务计划程序“结束”可能强制终止，不能当作正常退出，也不要批量杀掉同名程序。维护前禁用任务，确认具体进程已退出再更新。

可编辑的启动配置示例

日志与更新步骤

Server 日志
<data-dir>/logs/server.log。--verbose 增加终端诊断输出。服务管理器日志排查启动、账号、路径问题，Rovai 日志排查 Host 行为。
更新前
先读 Server 发布说明，完成或停止当前工作，停止对应进程及启动管理器，备份数据根目录与项目文件，记录版本和启动参数。
安装新版本
用目标 Release 安装器及明确版本重新安装，保留原数据目录。Windows 安装器不会替你停止正在运行的程序。0.4.1 没有 rovai-server upgrade 命令。
更新后
重启同一实例，确认版本、登录、队员配置、项目路径及原会话。Desktop 的升级机制不会更新独立安装的 Server。

保存与备份哪些内容

程序 revisions 不是工作台数据备份。停止实例后复制整个数据目录，包括数据库、认证状态、受管 Skills 与配置。备份可能包含私密会话和可用认证材料，应按凭据保护。

项目目录另行备份，包括未提交文件。智能体登录 / 配置可能在 Rovai 根目录外，来源附件也可能引用外部路径。只复制数据库不会保存这些内容。

需要回退时保留升级前停机快照及匹配安装包。较保守的恢复方式是在相同绝对数据根目录原位还原；不要假定旧程序能读取已迁移数据库。把数据根目录复制到新路径或另一主机，不属于已说明的自动迁移。

依赖备份前先在隔离环境检查恢复方案。不要让两个 Host 使用同一实时数据目录，也不要删除实例锁 / 身份文件绕过拒绝。

按现象排查

地址打不开
依次检查主机唤醒、进程运行、监听 IP / 端口、局域网或私网路由、防火墙。HTTPS 再查 DNS、证书与代理。
页面可打开但登录失败
使用同一实例 Token，核对外部来源和代理请求头。另一个数据根目录的 Token 无法登录当前实例。
登录后智能体不可用
检查主机进程账号、服务 PATH、智能体安装、原生登录与模型权限。把智能体装在手机上不能解决主机问题。
关闭终端后服务停止
当前是前台运行。按上文配置一种系统启动方式，使用原数据根目录并检查日志。
请求途中浏览器掉线
重新进入原会话查看原执行，再决定是否重发。画面断线不能说明执行是否完成。
提示 bundled Skill resources are unavailable
已在公开 macOS arm64 0.4.0 包的智能体启动前复现，包缺少所需内置资源。保留数据，按安装页升级到 Server 0.4.1。
提示 Matching WebUI is missing
保留完整发布包。macOS 0.4.0 按安装页直接启动 current/rovai-server。
符号链接或根目录锁拒绝
使用真实绝对数据路径。macOS /tmp 是符号链接，临时夹具应使用其规范 /private/tmp 路径。根目录锁表示可能有另一个运行进程持有实例。

接着阅读