帮你快速理解、总结文档立即下载
文档中心>WorkBuddy Enterprise>CodeBuddy>CodeBuddy Code>高级功能>Daemon 模式

Daemon 模式

最近更新时间：2026-08-26 17:59:30
我的收藏

本页目录：

Daemon 模式让 CodeBuddy Code 以后台常驻服务的方式运行，不依赖终端窗口。启动后提供完整的 HTTP API 和 Web UI，随时接受请求。
核心价值：把 CLI 从“用完即走”变成“随时待命”。

概念

概念
说明
Worker
运行中的 CLI 进程，通过 PID 文件注册在 ~/.codebuddy/sessions/
Daemon
后台常驻的 HTTP 服务进程（--serve 模式），通过 daemon start 管理
后台会话 (bg)
通过 --bg 启动的非交互式任务，自动输出日志到文件

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 stop
codebuddy 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 种类型，按优先级自动选择：
类型
路径
内容
触发条件
telemetry
~/.codebuddy/logs/{date}/{workspace}.log
所有模块的 Info/Warn/Error
始终（默认优先）
process
~/.codebuddy/logs/{name}.log
进程 stdout/stderr
仅 bg/daemon
debug
~/.codebuddy/debug/{sessionId}.txt
详细调试信息
需 --debug
transcript
~/.codebuddy/projects/{id}/{sessionId}.jsonl
对话历史
始终

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

环境变量

变量
说明
CODEBUDDY_SESSION_KIND
Worker 类型（interactive / bg / daemon）
CODEBUDDY_SESSION_NAME
后台会话显示名称
CODEBUDDY_SESSION_LOG
后台会话日志路径
CODEBUDDY_GATEWAY_AUTH
认证模式（none / password）

系统服务注册

将 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"
  }
}

平台支持

平台
后端
服务类型
配置路径
macOS
launchd
Launch Agent（用户级）
~/Library/LaunchAgents/com.codebuddy.daemon.plist
Linux
systemd
User Unit
~/.config/systemd/user/codebuddy-daemon.service
Windows
Task Scheduler
计划任务（用户级）
schtasks /tn "CodeBuddy Daemon"
所有平台均为用户级服务，无需管理员权限。

自动更新

系统服务 + 自动更新形成完整的零干预运维链路：
1. 系统登录 → 系统服务自动启动 daemon
2. 每小时 → 后台检查新版本并静默安装
3. 空闲时 → fork 新 daemon 进程 → 旧进程正常退出（不触发崩溃重启）
4. 崩溃时 → 系统服务自动恢复（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 的区别

特性
--serve
daemon start
生命周期
跟随终端，关闭终端则退出
后台常驻，独立于终端
启动方式
前台运行
fork detached 子进程
管理方式
Ctrl+C 停止
daemon stop/status/restart
多次启动
每次创建新进程
幂等，只维护一个 daemon
典型用途
临时开发调试
长期运行的服务

中国站