Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

服务管理

ZeroClaw 随附对 systemd（Linux）、launchctl（macOS）和 Task Scheduler（Windows）的一流服务集成。这三者都由同一个 CLI 接口驱动：

sh

zeroclaw service install     # 注册服务
zeroclaw service start       # 启动它
zeroclaw service stop        停止
zeroclaw service restart     # 停止 + 启动
zeroclaw service status      # 运行中 / 已停止，上次退出代码
zeroclaw service uninstall   # 删除它

平台相关的后端实现位于 crates/zeroclaw-runtime/src/service/ 中。你不必关心它们的细节，但了解它们的产出在调试时会有所帮助。

Linux：systemd

zeroclaw service install 会在 ~/.config/systemd/user/zeroclaw.service 写入一个用户作用域的单元文件。

单位：

  • Type=simple，代理进程保持在前台
  • ExecStart={cargo-bin}/zeroclaw daemon
  • Restart=always 配合 RestartSec=3
  • Environment=HOME=%h 和 PassEnvironment=DISPLAY XDG_RUNTIME_DIR，使无头浏览器工具能够创建配置文件/缓存目录并访问用户会话
  • WantedBy=default.target

手动控制（systemd）

sh

systemctl --user start zeroclaw
systemctl --user stop zeroclaw
systemctl --user status zeroclaw
systemctl --user enable zeroclaw     # 登录时启动

日志

sh

journalctl --user -u zeroclaw -f        # follow
journalctl --user -u zeroclaw --since 1小时前

环境变量覆盖（systemd）

当守护进程需要交互式 shell 中不存在的环境变量时，请使用用户服务覆盖：

sh

systemctl --user edit zeroclaw.service

例如，使用 credential_process 的 Bedrock 配置文件需要在服务环境中设置 AWS_PROFILE：

[Service]
Environment=AWS_PROFILE=zeroclaw-bedrock

保存覆盖文件后，重新加载并重启用户服务：

sh

systemctl --user daemon-reload
systemctl --user restart zeroclaw
journalctl --user -u zeroclaw -f

生成的用户服务设置了 HOME=%h，因此读取服务用户主目录下文件的提供程序代码可以解析诸如 ~/.aws/config 这样的路径。如果覆盖配置引用了可执行文件，请使用绝对路径；systemd 服务通常使用比交互式 shell 更小的 PATH。

在用户登录前启动

CLI 只会写入用户范围的单元（systemctl --user），默认在登录时启动、注销时停止。若要在无活动会话的无头服务器上保持 ZeroClaw 运行，请为该服务用户启用 lingering：

sh

sudo loginctl enable-linger $USER
systemctl --user enable --now zeroclaw

如果你需要一个真正的系统级单元（root 所有、/etc/systemd/system/、专用服务账户，或通过 SupplementaryGroups 配置硬件组），CLI 不会生成这样的单元；请改用 scripts/zeroclaw.service 中的系统级模板并自行安装。在 OpenRC 主机上，sudo zeroclaw service install 确实会配置一个专用的 zeroclaw 用户和系统路径（见下文）。

Linux：OpenRC

当存在 /run/openrc 时自动检测（Alpine、某些 Gentoo 配置）。

sh

zeroclaw service install   # 写入 /etc/init.d/zeroclaw
rc-service zeroclaw start
rc-update add zeroclaw default    # 开机启动

OpenRC 会将守护进程输出保存在 /var/log/zeroclaw/access.log 和 /var/log/zeroclaw/error.log 中。每个文件保留的最新输出不超过 8 MiB。升级后重新安装并重启服务，以便生成的 init 脚本使用有大小上限的日志记录进程。

macOS：LaunchAgent

zeroclaw service install 会写入 ~/Library/LaunchAgents/com.zeroclaw.daemon.plist 并加载它。

sh

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

日志会写入 <config-dir>/logs/ 下的 daemon.stdout.log 和 daemon.stderr.log（默认安装时为 ~/.zeroclaw/logs/）。Homebrew 安装则会写入 $HOMEBREW_PREFIX/var/zeroclaw/logs/。每个 launchd 捕获文件保留的最近输出不超过 8 MiB。升级后请重新安装并重启服务，以便生成的 LaunchAgent 使用有大小上限的捕获方式。

由 Homebrew 管理

如果通过 Homebrew 安装，brew services 是首选的接口：

sh

brew services start zeroclaw
brew services restart zeroclaw
brew services info zeroclaw

不要混用 zeroclaw service CLI 命令和 brew services，请选择其中一种。两者最终都会写入 plist 文件，同时使用会让 launchctl 产生混乱。

Windows：任务计划程序

zeroclaw service install 会创建一个名为 ZeroClaw Daemon 的每用户计划任务：

  • 触发器：登录时（/SC ONLOGON）
  • 运行级别：LIMITED（以当前用户身份运行，未提升权限）
  • 操作：运行安装包装脚本 zeroclaw-daemon.cmd，该脚本将启动 zeroclaw daemon

在任务计划程序 GUI (taskschd.msc) 中，依次展开“任务计划程序库 → ZeroClaw Daemon“进行验证。

日志将写入 <config-dir>\logs\，文件名为 daemon.stdout.log 和 daemon.stderr.log（默认安装路径为 %USERPROFILE%\.zeroclaw\logs\）：

cmd

type %USERPROFILE%\.zeroclaw\logs\daemon.stdout.log

手动控制（任务计划程序）

该任务通过 zeroclaw service start|stop|status 来驱动，它们对 ZeroClaw Daemon 任务分别封装了 schtasks /Run、/End 和 /Query。你也可以直接管理它：

cmd

schtasks /Run /TN ZeroClaw Daemon
schtasks /End /TN ZeroClaw Daemon
schtasks /Query /TN ZeroClaw Daemon /FO LIST

该 CLI 仅安装每个用户的 ONLOGON 任务；它不会注册 LocalSystem Windows 服务。如需真正的系统服务，请自行使用第三方监管程序（例如 NSSM）封装该二进制文件。

配置路径解析

服务从安装时解析到的目录读取配置。优先级（首个匹配项生效）：

  1. $ZEROCLAW_CONFIG_DIR（配置文件直接位于 $ZEROCLAW_CONFIG_DIR 下）
  2. $ZEROCLAW_DATA_DIR
  3. $ZEROCLAW_WORKSPACE（已弃用，建议使用 ZEROCLAW_DATA_DIR；将解析 $ZEROCLAW_WORKSPACE 或旧版同级目录 .zeroclaw/）
  4. 仅在 macOS 上，通过 Homebrew 安装时的 Homebrew 配置目录（$HOMEBREW_PREFIX/var/zeroclaw/）
  5. 默认为 ~/.zeroclaw/（Linux/macOS）或 %USERPROFILE%\.zeroclaw\（Windows）

ZEROCLAW_CONFIG_DIR 会覆盖所有其他设置；与 ZEROCLAW_DATA_DIR 或 ZEROCLAW_WORKSPACE 一同设置时会记录一条警告并忽略其他项。

如果你的服务似乎忽略了配置更改，请检查守护进程解析的是哪个路径，zeroclaw status 会报告当前生效的配置文件，并且运行时会在启动时记录一行解析来源信息：

sh

zeroclaw status

输出中包含其解析所依据的配置文件路径。

自动更新

该服务不会自动更新。这是有意为之；你可以自行决定何时采用新代码。请订阅 GitHub 发布动态或 Discord 的 #releases 频道（参见 Contributing → Communication）。

另见