服务与守护进程

本页面是 Setup → Service management 的运维侧配套文档；该页面介绍了服务的安装与卸载。本页面则介绍如何运行服务：调优、资源限制、优雅重启以及多工作区配置。

选择用户范围与系统范围

范围	适用于	缺点
用户	笔记本电脑、单用户开发机、简单部署	仅在用户已登录时运行（Linux 桌面环境、macOS），除非你启用了“持续运行”（lingering）。
系统	无头服务器、SBC、VPS、多用户主机	需要 root 权限才能安装；会创建自己的用户账户

在桌面 Linux 上，启用用户服务持久化（lingering），使用户服务在注销后仍然保持运行：

sh

loginctl enable-linger $USER

无需停留，用户范围的 systemd 服务会在最后一个会话关闭时停止。

重启行为

已安装的 systemd 用户单元（~/.config/systemd/user/zeroclaw.service）使用：

Restart=always
RestartSec=3

systemd 会在守护进程以任何方式退出后，以 3 秒的退避间隔重启它。这里没有退出码白名单，因此遇到错误配置便快速失败的守护进程会反复重启；请修复配置并执行 systemctl --user restart zeroclaw，而不要指望服务自行放弃。

在 macOS 上，LaunchAgent（~/Library/LaunchAgents/com.zeroclaw.daemon.plist）将 RunAtLoad 和 KeepAlive 设置为 true，因此 launchd 会保持守护进程运行，并在其退出时重新启动它。

在 Windows 上，zeroclaw service install 会注册一个 Task Scheduler 任务，该任务在 LIMITED 运行级别下由 ONLOGON 触发。它会在登录时启动守护进程；但不会添加失败时自动重启的策略。

优雅关闭

在 Unix 系统上，守护进程会捕获 SIGINT 和 SIGTERM；在 Windows 系统上，它会捕获 Ctrl+C（ctrl_c）。其中任何一个都会触发干净的关闭流程：守护进程会停止其通道服务器和网关监听器，然后退出。

SIGHUP 会被忽略（守护进程保持运行）。通过 /admin/reload 端点请求的重新加载会原地重启守护进程循环，而不是退出。

会话内存和会话状态在运行期间会以增量方式写入 SQLite，而不是缓冲到关闭时才写入，因此正常停止并不依赖于刷新步骤。工具回执是会话中的带内 HMAC 令牌，而非单独的磁盘日志。强制 SIGKILL 会跳过正常的通道拆除流程，但不会损坏已提交的内存；只有正在写入过程中的智能体回合会丢失。

手动启动以进行调试

跳过服务，直接运行守护进程：

sh

zeroclaw service stop     # 如果服务正在运行，则释放网关端口
zeroclaw daemon

zeroclaw daemon 在前台运行，将日志输出到 stderr，与服务运行的进程相同，只是没有服务托管框架。适用于以下场景：

诊断服务吞掉的启动失败
在 gdb / lldb 下运行
在提交配置更改之前进行测试

使用 Ctrl-C 终止，其优雅关闭语义与 SIGTERM 相同。

资源限制

Linux：systemd

添加到 drop-in 中：

sh

systemctl --user edit zeroclaw.service

[Service]
MemoryMax=2G
CPUQuota=200%            # two cores
LimitNOFILE=16384        # if opening many channel sockets

重新加载并重启：

sh

systemctl --user daemon-reload
systemctl --user restart zeroclaw

macOS：launchd

编辑 ~/Library/LaunchAgents/com.zeroclaw.daemon.plist：

<key>SoftResourceLimits</key>
<dict>
  <key>NumberOfFiles</key>
  <integer>16384</integer>
</dict>

卸载并重新加载 plist 以应用更改：

sh

launchctl unload ~/Library/LaunchAgents/com.zeroclaw.daemon.plist
launchctl load ~/Library/LaunchAgents/com.zeroclaw.daemon.plist

Docker

Compose

服务:
  zeroclaw:
    图像: ghcr.io/zeroclaw-labs/zeroclaw:latest
    内存限制: 2G
    cpus: 2.0
    ulimits:
      nofile: 16384

运行多个工作区

每个 ZeroClaw 守护进程拥有一个配置目录（其中包含其 data/ 目录）。要并排运行两个守护进程，请通过 --config-dir（或 ZEROCLAW_CONFIG_DIR 环境变量）为每个守护进程指定各自的配置目录：

sh

zeroclaw --config-dir ~/.zeroclaw-home daemon
zeroclaw --config-dir ~/.zeroclaw-work daemon

每个实例读取自己的配置、自己的 data/（记忆、会话）、自己的网关端口（按配置设置）以及自己的频道绑定。记忆保持独立；某个配置目录中的 Telegram 机器人不会知道另一个的存在。

zeroclaw service install 始终安装单个指向默认配置目录的单元；它没有用于命名实例或为实例传参的标志。若要将多个实例作为持久化服务运行，请手动编写第二个单元文件（将 ~/.config/systemd/user/zeroclaw.service 复制为一个新名称），并在其 ExecStart 中传入 --config-dir <dir>，然后单独启用它。

不要让两个守护进程指向同一个配置目录。SQLite 是单写入模式；第二个守护进程会在启动时失败。

观察重启和崩溃

sh

# Linux
journalctl --user -u zeroclaw --since 1 天前 | grep -E 已启动|已停止|失败

# macOS
log show --predicate `process == "zeroclaw"` --last 1d | grep -E `'start|stop|error'`

如果你看到反复重启，请启用调试日志（通过单元文件的 Environment= 设置 RUST_LOG=debug），并让其再崩溃一次以捕获完整的堆栈跟踪。

ZeroClaw Docs