zouk-daemon

English

Zouk 平台的机器端 daemon 进程。连接 zouk-server，按指令启动/停止 AI agent 进程（Claude、Codex、Hermes、Kimi、VikingBot），并为每个 agent 注入 MCP server 提供工具访问。

安装

npx @openviking/zouk-daemon@latest --server-url wss://your-zouk-server --api-key sk_machine_xxx

daemon 会在启动时和每 24h 检查一次 npm 上的新版本。检测到新版本会自动 npm install -g @openviking/zouk-daemon@latest，然后自动重启进入新版本——无需 supervisor（见下方 自动更新）。

Docker

仓库内的 Dockerfile 会构建一个预装 Claude Code 和 Codex 的镜像。镜像连接 server 只需要 machine key——AI 的 endpoint/key 由 zouk-server 按 agent 下发（只有想设默认值时才需要作为环境变量传入）。

# 构建（claude/codex 在构建期预装）
docker build -t zouk-daemon:local .

# 运行——machine key 和 server URL 通过环境变量传入
docker run -d --name zouk-daemon \
  -e ZOUK_SERVER_URL=wss://your-zouk-server \
  -e ZOUK_API_KEY=sk_machine_xxx \
  -v zouk-home:/home/zouk \
  zouk-daemon:local

或用 Compose——把 .env.example 复制为 .env，填入 ZOUK_SERVER_URL / ZOUK_API_KEY，然后：

docker compose up -d --build

说明：

• 以非 root 的 zouk 用户（UID 1000）运行——这是必需的，因为 Claude Code 的 --dangerously-skip-permissions 拒绝以 root 身份运行。
• 镜像内置 ZOUK_RUNTIME_ALLOWLIST=claude,codex，daemon 只接受镜像实际安装的 runtime；扩展镜像时可覆盖。
• 镜像内禁用了 daemon 自动更新（ZOUK_DISABLE_AUTO_UPDATE=1）——版本由镜像固定，升级请重新构建。
• zouk-home 卷持久化 agent 工作区、session 和 CLI 登录态，重启不丢失。
• daemon 从 npm 安装（@openviking/zouk-daemon）；构建期可用 --build-arg DAEMON_VERSION=x.y.z --build-arg CLAUDE_CODE_VERSION=x.y.z --build-arg CODEX_VERSION=x.y.z 固定版本。docker-publish.sh 会把 DAEMON_VERSION 锁到 package.json 的版本，使镜像 tag 与烤进去的 daemon 版本一致。

发布

docker-publish.sh 一步构建多架构（amd64+arm64）镜像并推送到 registry——单架构主机上无法用普通 docker push 产出多架构 manifest。

docker login zouk-cn-beijing.cr.volces.com   # 一次性
./docker-publish.sh                          # 打 :<package.json 版本> + :latest
./docker-publish.sh 0.2.3                     # 指定版本

目标可用 REGISTRY / NAMESPACE / REPO / PLATFORMS 环境变量覆盖（默认 zouk-cn-beijing.cr.volces.com/zouk/zouk-daemon、linux/amd64,linux/arm64）。

从源码运行

# 安装依赖
npm install

# 构建
npm run build

# 启动（连接到你的 zouk-server）
npm run dev -- --server-url ws://localhost:7777 --api-key 1007

--api-key 1007 是开发模式的 debug key，生产环境使用 sk_machine_ 前缀的正式密钥。

本地开发

用 mock server 代替真实 zouk-server 进行开发测试：

# 终端 1：启动 mock server
npm run mock-server -- --scenario single-agent

# 终端 2：启动 daemon
npm run dev -- --server-url ws://localhost:3001 --api-key test

Mock server 场景：

| 场景 | 说明 | | --- | --- | | idle | 只建立连接，不做任何操作 | | single-agent | 启动一个 Claude agent，定期投递消息 | | multi-agent | 启动三个不同 runtime 的 agent | | stop-start | 测试 agent 的停止和重启 | | workspace | 测试工作区文件操作 |

CLI 参数

zouk-daemon [options]

  --server-url <url>    Zouk server 地址（必填，或设 ZOUK_SERVER_URL 环境变量）
  --api-key <key>       机器 API 密钥（必填，或设 ZOUK_API_KEY 环境变量）
  --hostname <name>     覆盖主机名（可选）
  --data-dir <path>     数据目录（默认 ~/.zouk）
  --no-ovcli-conf       不写 per-agent ovcli.conf，只给 agent 注入
                        OPENVIKING_URL / OPENVIKING_API_KEY（或设 ZOUK_WRITE_OVCLI_CONF=0）
  --runtime-allow <csv> 本机只允许启动列出的 runtime，如 claude,codex
                        （或设 ZOUK_RUNTIME_ALLOWLIST）
  --version             显示版本
  --help                显示帮助

本地策略覆盖

这两个参数按机器维度约束/覆盖 server 下发的行为：

• --no-ovcli-conf —— server 下发 OpenViking 凭据时，daemon 默认会在 ~/.zouk/agents/<id>/.ov/ovcli.conf 写一份 per-agent 配置，并注入完整的 OPENVIKING_URL/API_KEY/ACCOUNT/USER + OPENVIKING_CLI_CONFIG_FILE。加上此参数后不写文件，只注入 OPENVIKING_URL 和 OPENVIKING_API_KEY，account/user 交给 OV CLI 从 key 自动取 default。
• --runtime-allow —— 逗号/空格分隔的 runtime 白名单。不在名单内的 agent:start 会被拒绝（agent 置为 inactive）。适合把某台机器专门用于特定 runtime。

支持的 Runtime

| Runtime | 二进制 | 说明 | | --- | --- | --- | | claude | claude | Claude Code CLI，stream-json 协议 | | codex | codex | Codex CLI，JSON-RPC 协议 | | gemini | gemini | Gemini CLI，ACP/JSON-RPC 协议 | | hermes | hermes | Hermes ACP，JSON-RPC 2.0 协议 | | kimi | kimi | Kimi CLI，wire 协议 | | vikingbot | （内置 Node worker） | 一次性 bot，无需外部二进制 |

daemon 启动时自动检测本机可用的 runtime，并在 ready 消息中上报给 server。

项目结构

src/
├── index.ts            # CLI 入口
├── core.ts             # DaemonCore：WS 连接 + 消息分发
├── connection.ts       # WebSocket 客户端：重连、watchdog
├── agents/             # Agent 生命周期管理
├── agent-mcp/          # MCP server（每个 agent 独立进程）
├── drivers/            # Runtime 驱动（Claude/Codex/Gemini/Hermes/Kimi/VikingBot）
├── rpc/                # 工作区文件、OV 记忆、Skills 等 RPC 处理
└── lib/                # 日志、配置、路径工具

常用命令

npm run build       # tsup 构建 → dist/
npm run dev         # tsx watch 开发模式
npm run typecheck   # tsc --noEmit
npm test            # node:test 运行测试
npm run mock-server # 启动 mock server

自动更新

zouk-daemon 在启动时以及每 24h 会拉一次 npm registry。检测到新版本就执行 npm install -g @openviking/zouk-daemon@latest，然后自动重启进入新版本——从刚装好的全局包以相同参数重新拉起自身，不需要外部 supervisor（npx … @latest 一行命令在更新后也会继续运行）。

如果自重启无法定位全局安装（例如 spawn 被限制），daemon 会退回到以退出码 75（EX_TEMPFAIL）退出，由外部 supervisor 拉起新版本。

可选的 supervisor 配置（同样会在退出 75 后拉起新代码）：

# pm2
pm2 start zouk-daemon -- --server-url <url> --api-key <key>

# systemd（Restart=always 会在退出 75 后自动拉起新二进制）
[Service]
ExecStart=/usr/local/bin/zouk-daemon --server-url <url> --api-key <key>
Restart=always
RestartSec=2

# 简单的 shell 循环
while true; do zouk-daemon --server-url <url> --api-key <key> || sleep 2; done

设 ZOUK_DISABLE_AUTO_UPDATE=1 可以完全关闭自动更新；设 ZOUK_NPM_REGISTRY=<url> 可以指向私有 registry。