CodeBuddy Daemon 模式

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

一、概念

三、启动 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。

八、进程管理命令

# 列出所有活跃 Workercodebuddy 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 章节。

十、示例

# 列出所有 Workercurl http://127.0.0.1:8080/api/v1/workers# 启动 Daemoncurl -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"# 终止 Workercurl -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 注册为操作系统级服务，实现登录自动启动和崩溃自动恢复。

十六、安装 / 卸载

# 注册为系统服务并立即启动 daemoncodebuddy 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" }}

十七、平台支持

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

十八、自动更新

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

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

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

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

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

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

十九、管理命令对照

# macOS 原生管理launchctl list | grep codebuddylaunchctl stop com.codebuddy.daemonlaunchctl start com.codebuddy.daemon# Linux 原生管理systemctl –user status codebuddy-daemonsystemctl –user stop codebuddy-daemonsystemctl –user start codebuddy-daemon# Windows 原生管理schtasks /query /tn "CodeBuddy Daemon"

21、开发服务器常驻

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

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

22、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 文档。

23、多人共享 Agent

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

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

24、后台批量任务

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

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

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

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

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

26、IDE 扩展后端

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

27、与 –serve 的区别