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，然后以退出码 75 退出，等 supervisor 拉起新版本（见下方 自动更新）。

从源码运行

# 安装依赖
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）
  --version             显示版本
  --help                显示帮助

支持的 Runtime

| Runtime | 二进制 | 说明 | | --- | --- | --- | | claude | claude | Claude Code CLI，stream-json 协议 | | codex | codex | Codex CLI，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/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，然后以退出码 75（EX_TEMPFAIL）退出 —— 由外部 supervisor 拉起新版本。

推荐的 supervisor 配置：

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