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 使用有界捕获。zeroclaw service logs 会显示两个文件中包含输出的那个，因此只写入 stdout 的守护进程也能被看到；--follow 会同时监视两个文件，因此启动后写入 daemon.stderr.log 的故障仍会传递给正在运行的查看器。当显示多个文件时，tail 会为每个代码块添加 ==> path <== 标题。

由 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.exe --config-dir <config-dir> service run-windows-daemon；内部运行器负责守护进程子进程及其输出捕获
  • Window：Windows 当前会为这个交互式计划任务附加一个空的控制台窗口。服务运行期间请保持该窗口打开；关闭它可能会导致 runner 和 daemon 停止。不显示该窗口的后台启动方式已在 #10991 中跟踪。

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

日志写入 <config-dir>\logs\，文件名为 daemon.stdout.log 和 daemon.stderr.log（默认安装时为 %USERPROFILE%\.zeroclaw\logs\）。每个文件保留的近期输出上限为 8 MiB。

要替换现有任务（包括较早的 .cmd 包装器或此直接运行器），请先运行 schtasks /Change /TN "ZeroClaw Daemon" /Disable，重启 Windows，然后运行 zeroclaw service install。除 Disabled 之外的任何状态下，安装程序都会拒绝替换任务，因为任务计划程序的 Ready 状态无法证明其进程已退出；仅运行 zeroclaw service stop 是不够的。安装程序会检查任务是否处于 Disabled 状态，但无法验证 Windows 是否已重启，因此请在重新安装前完成该步骤。旧的包装器文件可以保留，但不再使用。运行器要求配置根目录和捕获文件归任务账户所有，并拒绝重解析点（reparse-point）路径，同时限制其 ACL。任务计划程序操作路径中包含字面 % 符号的情况不受支持。

zeroclaw service logs 会打印其中有输出的文件。使用 --follow 时，会先显示其他文件的内容，然后持续跟踪 daemon.stdout.log；如果只有 daemon.stderr.log 有输出，则跟踪该文件。这是因为 Get-Content -Wait 只能跟踪单个路径。要直接读取某个文件：

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）。

另见