命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
打印后台会话主管的状态
claude daemon statusclaude daemon statusclaude daemon status 是 Claude Code CLI 的一个诊断子命令,用于直接查询后台会话主管进程(supervisor / daemon)的运行状态。
背景主管是 Claude Code 在你首次启动 --bg 后台会话时自动创建的一个每用户独立进程。它独立于任何终端窗口运行,充当所有后台 agent 会话的父进程和调度中心,即使关闭终端后台任务也能继续执行。
| 属性 | 值 |
|---|---|
| 正式支持版本 | v2.1.141+ |
| 命令类型 | CLI 子命令(shell 中运行) |
| 交互性 | 非交互,打印一次即退出 |
| 平台 | macOS、Linux、Windows(Windows 有专属改进) |
| 订阅要求 | 无特殊要求,标准 Claude Code 账户即可 |
claude daemon status
直接在任意 shell 中运行,无需事先进入交互式 Claude 会话。
命令会打印一份状态摘要。官方未公开固定的输出格式,下面的字段与示例仅为社区整理的示意,字段名/格式以你实际运行的输出为准:
Supervisor: reachable
Version: 2.1.154
PID: 83421
Socket dir: /home/user/.claude/daemon
Sessions: 3 live
| 字段(示意) | 说明 |
|---|---|
Supervisor | reachable(可达)或 unreachable(不可达) |
Version | 当前运行的 daemon 版本号 |
PID | 主管进程的系统 PID |
Socket dir | daemon 通信用 socket 文件所在目录 |
Sessions | 当前活跃的后台会话数量 |
据 issue #58869,自 v2.1.141 起,在 Windows 上当 daemon 的底层 pipe-key 文件出问题(被锁定/不可读)时,该命令会显示底层文件错误,而不是模糊的"连接失败",便于排查守护进程启动问题。
具体错误输出的精确格式官方未公开,本指南不再给出杜撰的示例字符串;以你机器上的实际输出为准。
/doctor 使用/doctor 是在交互式 Claude 会话内部运行的诊断命令,它也会读取 daemon 状态(尤其在 Windows)。两者互补:
claude daemon status/doctordaemon 的所有状态存储在 ~/.claude/ 目录下:
| 文件路径 | 内容 |
|---|---|
~/.claude/daemon.log | 主管进程的运行日志 |
~/.claude/daemon/roster.json | 所有运行中会话的注册表,daemon 重启后用于重新连接 |
~/.claude/jobs/<id>/state.json | 单个会话的状态快照(供 Agent View 读取) |
查看 daemon 日志:
tail -f ~/.claude/daemon.log
日志的具体条目格式官方未公开,本指南不再给出杜撰的示例行。
| 变量 | 作用 |
|---|---|
CLAUDE_CONFIG_DIR | 覆盖默认配置目录(官方 credential/config 文档已确认此变量);切换后 daemon 的会话 roster 也随该目录变化 |
早期本指南列出的
CLAUDE_CODE_DISABLE_AGENT_VIEW环境变量在官方 CLI/env-vars 文档及相关 issue 中均无记录,已移除。
# 检查 daemon 是否在线
if ! claude daemon status 2>&1 | grep -q "reachable"; then
echo "daemon 未就绪" >&2
fi
# 启动后台 agent —— 首个 --bg 会自动拉起 daemon,通常无需手动 start
claude --bg "run the test suite"
注:
claude daemon start/stop/restart是否为受支持的 CLI 子命令,官方 CLI reference 命令表中尚无明确记录(issue #58869 仅记录了daemon status的文档缺口)。daemon 通常由首个claude --bg自动管理,本指南不再把 start/stop/restart 当作既成事实的子命令呈现。
| 约束 | 说明 |
|---|---|
| 机器休眠/关机 | 后台会话在机器进入休眠或关机后停止;daemon 不是系统级服务,无法在休眠中持续 |
| 二进制升级短暂中断 | brew upgrade 或自动更新安装新二进制时,daemon 会退出并重新启动;此窗口内运行中的 agent 可能短暂报错 |
| Windows pipe-key 锁 | Windows 上 pipe-key 文件出问题时 daemon 无法启动,v2.1.141 前只返回通用错误;v2.1.141 起会显示底层文件错误 |
| 未在官方文档索引 | 截至 v2.1.154,该命令尚未出现在 code.claude.com/docs/en/cli-reference 的命令表中(GitHub issue #58869 记录了这一文档缺口) |
| 命令 / 机制 | 目标 | 是否交互 | 适用场景 |
|---|---|---|---|
claude daemon status | 查询 daemon/supervisor 进程本身 | 否 | 脚本诊断、排障 |
claude agents | 列出并管理所有后台 会话 | 是(TUI) | 日常查看、attach、kill |
/doctor | 全环境诊断(含 daemon 状态) | 是(会话内) | 活跃会话中快速体检 |
claude logs <id> | 查看某个会话的日志 | 否 | 调试具体任务输出 |
claude daemon status,确认 supervisor 是否 reachable,据此判断问题在 daemon 还是别处,而不是盲目重启终端。claude daemon status 会精确显示 pipe-key 文件的锁定路径和错误码,比查看通用错误节省时间。claude daemon status 断言 daemon 在线,避免无声失败。brew upgrade claude 或 npm install -g @anthropic-ai/claude-code 后,用 claude daemon status 确认新版本的 daemon 已正常重启并版本号已更新。CLAUDE_CONFIG_DIR 使用不同目录的 daemon 时,claude daemon status 可帮助确认当前 shell 环境指向哪个实例及其 PID。误以为 daemon 需要手动启动:正常情况下 daemon 由第一个 claude --bg 命令自动拉起,不需要在每次使用前手动启动。
claude agents 挂起却不用 daemon status 检查:当 claude agents 或 claude logs <id> 出现无响应时,很多用户直接杀进程。正确做法是先运行 claude daemon status 确认 supervisor 可达性,再决定后续处理。
Windows 上用了旧版本(<v2.1.141):v2.1.141 之前 Windows 上的 daemon status 只返回"连接失败"而不显示具体原因,极难排查。如果在 Windows 上遇到困难,请先 claude --version 确认版本,按需升级。
休眠后后台任务"消失"当做 daemon 崩溃:机器休眠/唤醒后,后台会话可能受影响,但这通常不代表 daemon 本身崩溃 —— daemon status 此时多半仍显示 reachable。先用 daemon status 确认,而非直接断定 daemon 挂了。(关于具体的休眠/时钟处理机制,官方文档无公开记录,此处不做断言。)
修改 CLAUDE_CONFIG_DIR 后找不到之前的会话:daemon 的会话 roster 绑定到特定配置目录。切换 CLAUDE_CONFIG_DIR 后运行 claude daemon status 会显示一个新的空实例,原有会话在旧目录的 roster.json 中,需切回原 CLAUDE_CONFIG_DIR 才能访问。
后台会话由 daemon 托管;要结束某个会话,在该会话内运行 /stop,或用 claude stop <id>(会话管理命令以官方 CLI reference 为准)。
claude daemon stop/restart等显式 daemon 子命令在官方 CLI reference 中暂无明确记录,本指南不再将其作为既成事实给出。
卸载 Claude Code 时(npm uninstall -g @anthropic-ai/claude-code 或 brew uninstall claude-code),daemon 进程会随之终止,但 ~/.claude/ 目录下的状态文件不会自动删除,如需彻底清理需手动 rm -rf ~/.claude/daemon ~/.claude/daemon.log ~/.claude/jobs/。
claude daemon status diagnostics · Issue #58869 · anthropics/claude-coderoster.json / jobs/<id>/state.json 路径）改进命令对版本偏差行为的解释说明。