Daemon 模式

后台常驻服务的方式运行，不依赖终端窗口。启动后提供完整的 HTTP API 和 Web UI，随时接受请求。

核心价值：把 CLI 从“用完即走”变成“随时待命”。

概念

Daemon 管理

启动 Daemon

# 启动 daemon（后台运行，自动分配端口）
codebuddy daemon start

# 指定端口
codebuddy daemon start --port 8080

# 指定绑定地址（允许远程访问）
codebuddy daemon start --host 0.0.0.0

# 指定权限模式（默认为 delegate 委托模式）
codebuddy daemon start --permission-mode default

# 传递其他标准参数（model、mcp-config 等会自动继承）
codebuddy daemon start --model claude-sonnet-4-20250514 --mcp-config ./.mcp.json

Daemon 启动后以 detached 进程运行，父进程立即退出。本地地址默认免密访问，非本地地址自动开启密码认证。

默认委托模式：Daemon 默认以委托（delegate）模式运行——主 agent 只负责协调调度，不直接修改代码。所有实现工作通过 subagent 完成。可通过 --permission-mode 切换为其他模式。

参数继承：daemon start 时指定的标准 CLI 参数（--model、--permission-mode、--mcp-config、--tools、--agent、--settings 等）会自动继承到 daemon 子进程中。

幂等启动：多次执行 daemon start 不会创建多个 daemon。如果已有 daemon 在运行，会直接返回现有 daemon 的信息。

查看状态

codebuddy daemon status# {"status":"running","pid":12345,"endpoint":"http://127.0.0.1:51862","startedAt":1775498920401}

停止 / 重启

codebuddy daemon stopcodebuddy daemon restart

后台会话

启动后台任务

# 后台执行任务
codebuddy --bg "实现登录页面"

# 指定名称（便于查找）
codebuddy --bg --name feature-login "实现登录页面"

后台会话以 --print -y 模式运行（无 TUI + 跳过权限确认），stdout/stderr 重定向到 ~/.codebuddy/logs/{name}.log。

进程管理命令

# 列出所有活跃 Worker
codebuddy ps

# 查看后台会话日志
codebuddy logs feature-login

# 持续跟踪日志（类似 tail -f）
codebuddy logs feature-login -f

# 附加到后台会话
codebuddy attach feature-login

# 终止后台会话
codebuddy kill feature-login

HTTP API

所有 Worker 和 Daemon 管理能力通过 REST API 暴露，Web UI 的 Workers 页面基于这些 API 构建。

详见 HTTP API 文档 中的 Workers & Daemon 章节。

示例

# 列出所有 Worker
curl http://127.0.0.1:8080/api/v1/workers

# 启动 Daemon
curl -X POST http://127.0.0.1:8080/api/v1/daemon/start \
  -H "Content-Type: application/json" \
  -d '{"port": 9090}'

# 查看 Worker 日志（遥测日志）
curl "http://127.0.0.1:8080/api/v1/workers/12345/logs?type=telemetry&tail=100"

# 终止 Worker
curl -X DELETE http://127.0.0.1:8080/api/v1/workers/12345

Web UI

--serve 模式启动后，Web UI 提供三个管理页面：

Workers — Worker 进程管理和 Daemon 控制

Logs — 独立日志查看器，支持 Worker 选择、日志类型切换、关键词搜索

Metrics — 系统资源监控和各 Worker 进程级指标

日志体系

日志 API 支持 4 种类型，按优先级自动选择：

PID 文件注册表

每个 CLI 进程启动时在 ~/.codebuddy/sessions/ 注册 PID 文件：

~/.codebuddy/sessions/├── 12345.json          # 本地进程（PID 作为文件名）├── 67890.json          # 另一个本地进程└── manual-abc123.json  # 手动添加的远程 Worker

PID 文件内容：

{  "pid": 12345,  "sessionId": "interactive-12345",  "cwd": "/home/user/project",  "startedAt": 1775498920401,  "kind": "interactive",  "url": "http://127.0.0.1:8080",  "mode": "local",  "version": "2.78.1",  "hostname": "my-machine"}

进程存活通过 kill -0 检测，手动远程 Worker 通过心跳超时检测（2 分钟）。

环境变量

系统服务注册

将 daemon 注册为操作系统级服务，实现登录自动启动和崩溃自动恢复。

安装 / 卸载

# 注册为系统服务并立即启动 daemon
codebuddy daemon install

# 指定端口和权限模式
codebuddy daemon install --port 8080 --permission-mode bypassPermissions

# 移除系统服务注册
codebuddy daemon uninstall

安装后 codebuddy daemon status 会显示系统服务状态：

{  "status": "running",  "pid": 42567,  "endpoint": "http://127.0.0.1:9527",  "systemService": {    "installed": true,    "backend": "launchd",    "configPath": "/Users/xxx/Library/LaunchAgents/com.codebuddy.daemon.plist"  }}

平台支持

所有平台均为用户级服务，无需管理员权限。

自动更新

系统服务 + 自动更新形成完整的零干预运维链路：

系统登录 → 系统服务自动启动 daemon

每小时 → 后台检查新版本并静默安装

空闲时 → fork 新 daemon 进程 → 旧进程正常退出（不触发崩溃重启）

崩溃时 → 系统服务自动恢复（KeepAlive / Restart=on-failure）

设计细节：系统服务配置为仅在非正常退出时重启。自动更新的 graceful restart 以 exit code 0 退出，不会触发系统服务的重启机制，新进程已经由更新流程自行 fork 出来了。

管理命令对照

# macOS 原生管理
launchctl list | grep codebuddy
launchctl stop com.codebuddy.daemon
launchctl start com.codebuddy.daemon

# Linux 原生管理
systemctl --user status codebuddy-daemon
systemctl --user stop codebuddy-daemon
systemctl --user start codebuddy-daemon

# Windows 原生管理
schtasks /query /tn "CodeBuddy Daemon"

使用场景

开发服务器常驻

日常开发时启动一次 daemon，之后通过浏览器或 API 随时与 AI 交互，不用每次都打开终端。

codebuddy daemon start --port 8080# 浏览器打开 http://127.0.0.1:8080 即可使用# 关闭终端后服务仍在运行

CI/CD 自动化后端

在 CI 流水线中启动 daemon 作为 Agent 服务，其他步骤通过 HTTP API 调用它执行代码审查、测试生成等任务。

# CI 启动
codebuddy daemon start --port 9090

# 其他 CI 步骤调用（body 为 Gateway Protocol 格式，须含 id/type）
curl -X POST http://127.0.0.1:9090/api/v1/runs \
  -H "Content-Type: application/json" \
  -H "X-CodeBuddy-Request: 1" \
  -d '{"id": "run-1", "type": "message", "payload": {"text": "审查这个 PR 的代码变更"}}'
# 响应: {"data": {"runId": "uuid-xxx", "status": "accepted"}}

说明：

/api/v1/runs 请求必须携带 X-CodeBuddy-Request 头，body 使用 Gateway Protocol 格式（id、type 为必填，prompt 文本放在 payload.text），字段详情见 HTTP API 文档。

多人共享 Agent

一台开发机上启动 daemon 绑定局域网地址，团队成员通过 Web UI 共同使用同一个 Agent 环境。

codebuddy daemon start --host 0.0.0.0 --port 8080# 同事访问 http://192.168.1.100:8080

后台批量任务

用 --bg 同时启动多个后台会话处理不同任务，通过 ps/logs/kill 管理。

codebuddy --bg --name "refactor-auth" "重构认证模块"
codebuddy --bg --name "add-tests" "给 utils 目录补充单元测试"
codebuddy --bg --name "fix-types" "修复所有 TypeScript 类型错误"

# 查看进度
codebuddy ps
codebuddy logs refactor-auth

微信/企业微信机器人后端

daemon 常驻运行作为聊天机器人的后端服务，通过长连接接收消息。

codebuddy daemon start# 配合远程控制功能连接微信/企业微信渠道

IDE 扩展后端

IDE 插件通过 ACP 协议连接到 daemon，提供 AI 编程辅助，避免每次打开 IDE 都重新启动 CLI 进程。

与 --serve 的区别