--bg 深度核查 v2.1.278 · 3 处待复核 · Claude Code

本页目录8

启动参数看官方文档

在后台启动会话并立即返回，打印会话 ID 和管理命令

Syntax

--bg <prompt>

示例

claude --bg "investigate the flaky test"

深度使用指南

最近核查 2026-09-21

· 来源 3 个

code.claude.comClaude Code CLI reference
code.claude.comManage multiple agents with agent view - Claude Code Docs
code.claude.comClaude Code error reference

· 含官方文档· v2.1.2783 处待复核断言

· 锚定 v2.1.278 · 距最新 v2.1.316 已 38 个 patch

它到底是什么

--bg（长形式 --background）把新会话作为 background agent 启动，并立即返回，终端里只打印会话的短 ID 和管理命令。会话本身由一个后台 supervisor 服务托管，所以关掉 agent view 或终端后它仍会继续运行。

接受的值：prompt 是位置参数，不是 -p 的值。
默认值：不传则为普通的前台交互会话。
官方文档说明，supervisor 在你第一次后台化会话或打开 agent view 时自动启动，无需手动管理。

启动后的输出形如：

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

如果托管后台会话的服务尚未运行，--bg 可能会先在上述输出之上打印 Starting background service…。

用法

# 基本用法
claude --bg "investigate the flaky test"

# 指定 agent view 中显示的会话名
claude --bg --name "flaky-test-fix" "investigate the flaky test"

# 以指定 subagent 作为会话主 agent
claude --agent code-reviewer --bg "address review comments on PR 1234"

# 指定模型 / effort / 权限模式
claude --bg --model opus "refactor the authentication module"
claude --bg --effort high "deep investigation of performance bottleneck"
claude --bg --permission-mode plan "review and suggest changes to the API"

# 用完整 session ID 在后台继续已有会话
claude --resume <full-session-id> --bg "pick up where you left off"

# 把 shell 命令作为后台 job 运行,而不是 Claude 会话
claude --bg --exec 'pytest -x'

启动后的管理命令：

命令	作用
`claude agents`	打开 agent view;`--json` 以 JSON 数组输出活动会话（`--json --all` 还包含已完成的后台会话），`--cwd <path>` 只显示该目录下启动的会话
`claude attach <id>`	在当前终端 attach 到后台会话
`claude logs <id>`	打印会话最近的输出
`claude stop <id>`	停止会话（也可用 `claude kill`）
`claude respawn <id>`	重启会话（运行中或已停止），保留对话；`--all` 重启所有运行中的会话
`claude rm <id>`	从列表中移除会话

与其他 flag 的组合 / 互斥

flag	关系
`-p` / `--print`	互斥。Claude Code 在创建任何会话之前就会拒绝该组合，报错 `--bg and --print conflict`
`--name`	可组合，设置 agent view 里的显示名，替代自动生成的名字
`--agent`	可组合，以指定 subagent 作为会话主 agent；名称不匹配任何已定义的 subagent 时启动失败：打印 `no agent named` 警告并仍报告会话已后台化，但会话随即以 `--agent '<name>' not found` 错误退出
`--exec`	可组合，把 shell 命令作为 PTY-backed 后台 job 运行，在 agent view 中显示为一行
`--model` / `--effort`	可组合，用于指定该会话的 model / effort;`claude agents --effort` 接受的值与顶层 `--effort` 相同，包括 `ultracode`
`--permission-mode`	可组合，可选 `plan`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`
`--dangerously-skip-permissions` / `--allow-dangerously-skip-permissions`	可组合；`--dangerously-skip-permissions` 等价于 `--permission-mode bypassPermissions`,`--allow-dangerously-skip-permissions` 会带入后台会话
`--resume`	可组合，继续已有对话需传完整 session ID;v2.1.257 及以后，Claude Code 要么在同一 ID 下继续该会话，要么以新 ID 启动一份副本，并打印 `note:` 行说明无法原地继续的原因
`--fork-session`	与 `--resume` 配合，显式启动一份会话副本

--bg 与 --continue、不带 ID 的 --resume、带名称或文件路径的 --resume 组合时，Claude Code 总是启动一份副本。想有意复制、并且不要那条提示时，加 --fork-session。

启动时的这些配置 flag 会带入后台会话：--mcp-config、--strict-mcp-config、--settings、--add-dir、--plugin-dir、--fallback-model、--allow-dangerously-skip-permissions。会话中用 /add-dir 添加的目录同样带入。

在 settings.json / env 的等价配置

--bg 本身没有对应的 settings.json 字段或环境变量，必须在命令行传入。以下是与后台会话相关的配置：

目的	flag	env	settings.json
启动后台会话	`--bg` / `--background`	无	无
整体关闭 background agents 与 agent view	无	`CLAUDE_CODE_DISABLE_AGENT_VIEW=1`	`"disableAgentView": true`
关闭后台会话的 worktree 隔离	无	无	`"worktree": { "bgIsolation": "none" }`
关闭进程重启时后台任务的 carry-over	无	`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`	无

管理员可以通过 managed settings 强制关闭 agent view。

运行约束 / 限制

约束	原因 / 说明
不能与 `-p` / `--print` 同用	`--print` 从不启动 `claude agents` 可以 attach 的交互会话
`bypassPermissions` 需要先接受免责声明	必须先交互式运行一次 `claude --dangerously-skip-permissions`，否则 `claude --bg --permission-mode bypassPermissions` 会被拒绝
默认在隔离的 git worktree 中写文件	编辑文件之前，Claude 会把会话移入 `.claude/worktrees/` 下的 worktree，让并行会话互不冲突
以下情况跳过 worktree	会话已在 linked worktree 内、被编辑文件在 linked worktree 内、工作目录不是 git 仓库且没有配置 `WorktreeCreate` hook、写入位置在工作目录之外
空闲进程会被回收	会话结束或在等你回复、且约一小时无人 attach 时，supervisor 会停掉进程释放资源；对话保留在磁盘，下次 attach 或回复时接着运行。用 `Ctrl+T` pin 住可让进程一直运行
进程意外退出会被重启	supervisor 在运行期间会重启意外退出的进程；权限模式、model、effort 在重启后保持不变

后台会话的状态文件位置：

路径	内容
`~/.claude/daemon.log`	supervisor 日志
`~/.claude/daemon/roster.json`	运行中的后台会话列表
`~/.claude/jobs/<id>/state.json`	agent view 显示的单会话状态
`~/.claude/jobs/<id>/tmp/`	单会话临时目录（会话内有 `CLAUDE_JOB_DIR` 环境变量指向 `~/.claude/jobs/<id>`）

经典使用场景

并行处理多个任务：每个 claude --bg "..." 是独立会话，各自写自己的 worktree，之后用 claude agents 统一查看。
换一个自定义 subagent 后台跑：claude --agent code-reviewer --bg "..."。
把长时间的命令放到后台：claude --bg --exec 'pytest -x' 以后台 job 运行测试，并在 agent view 里查看。
脚本里查看后台会话：claude agents --json 输出 JSON 数组，--json --all 包含已完成的会话。
在后台接着做已有对话：claude --resume <full-session-id> --bg "..."。

常见坑

想要非交互输出却用了 --bg:--bg 不是 headless 模式，与 -p 互斥。需要把结果打印到 stdout 的脚本场景应使用 -p。
后台会话读取的是它所在目录的 settings：项目 settings 中的 env（例如 ANTHROPIC_MODEL 或 provider 变量）会作用于该目录下的每个后台会话。
shell 环境变量只有部分会传给后台会话：会话使用你派发它时那个 shell 的 PATH，并保留该 shell 的云 provider 选择（如 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX）、ANTHROPIC_DEFAULT_*_MODEL 别名以及导出的 CLAUDE_CODE_EXTRA_BODY。
只在 shell 里导出的网关 ANTHROPIC_BASE_URL 不一定生效：只有 supervisor 本身也是在导出了同一网关的 shell 中启动时，它（连同 ANTHROPIC_CUSTOM_HEADERS 和凭据）才会到达后台会话。官方建议把网关配置写进 settings 文件。
claude rm 会一并清理：它把会话从列表移除，同时在安全时删除 Claude 为它创建的 worktree。对话 transcript 仍保留在本机，可通过 claude --resume 找回。存在未推送提交时需要 --discard-unpushed <commit>@<worktree-id>，强制删除 worktree 用 --force-remove-worktree <worktree-id>。
--agent 名称写错会直接启动失败：会先打印 no agent named 警告并仍报告会话已后台化，但会话随即以 --agent '<name>' not found 错误退出。
进程重启时的 carry-over 有边界：后台 shell 命令、动态 workflow 和后台 subagent 会带到下一个进程，但正在运行的 monitor 和 subagent 启动的 shell 命令会随进程停止。

来源

Claude Code CLI reference（https://docs.claude.com/en/docs/claude-code/cli-reference 会 301 重定向到此）
Manage multiple agents with agent view - Claude Code Docs
Claude Code error reference

全网调研整理

典型场景

长时间运行任务（调查 flaky test、大规模重构）时不阻塞当前终端
并行启动多个独立 agent（前端/后端/测试分工），同步推进项目
脚本或自动化流程中以 session ID 触发并追踪 agent 执行结果
在另一终端或设备上通过 claude attach 随时接管后台任务
配合 /batch 将大规模代码库变更分拆为多个后台 subagent 同步执行

实用技巧

配合 --name <label> 给会话命名，替代难记的 hash ID，claude attach/logs/stop 均可用名称操作
用 claude agents 打开统一面板，优先响应 'needs input' 状态以免 agent 长时间阻塞等待
任务描述要精确（含目标目录、预期输出、约束条件），减少 agent 中途暂停等待人工干预
后台会话在 /resume 选择器中显示（标记 bg），可随时切回前台继续对话，或 /exit 分离不停止
用 tmux 或 screen 包裹终端会话，防止 SSH 断连导致 supervisor 进程意外退出

常见坑

会话依赖本机持续运行，关机或休眠后状态变为 stopped，需执行 claude respawn --all 恢复
多个 --bg 会话之间上下文完全隔离，一个会话的发现不会自动同步给其他 agent
多个后台 agent 并发写入相同文件会产生冲突，需事先规划各 agent 的文件边界或配合 worktrees 隔离

来源

最早记录ⓘ

≤v2.1.140

变化时间线（按版本倒序）

修复v2.1.299· 2026/10/14 · 19 天前

修复发给后台会话的 prompt 或回复以 --bg 开头时被当作参数、反复启动新会话的问题。

修复v2.1.286· 2026/10/01 · 2026/10/01

修复了在 Windows 上拒绝用不同大小写保存的信任记录的文件夹的问题

修复v2.1.281· 2026/09/24 · 2026/09/24

修复了后台会话在未通过工作区信任时仍然启动的问题

修复v2.1.280· 2026/09/23 · 2026/09/23

修复背景 session 无法运行 git、hooks 等 helper 程序

修复v2.1.277· 2026/09/19 · 2026/09/19

修复了当插件 LSP server 退出或关闭 stdin 时后台会话也退出的问题。

修复v2.1.265· 2026/09/09 · 2026/09/09

修复后台会话在空闲超时前被中断的问题

修复v2.1.251· 2026/08/29 · 2026/08/29

修复与 --model 组合在 Max plans 上仍要求使用积分的问题

修复v2.1.212· 2026/07/17 · 2026/07/17

修复了 Windows 上 PowerShell 5.1 被阻止时的 uv_spawn 错误

修复v2.1.206· 2026/07/10 · 2026/07/10

修复了 CLAUDE_CODE_EXTRA_BODY 环境变量被忽略的问题

修复v2.1.187· 2026/06/24 · 2026/06/24

修复了在 help 中未被列出的问题

修复v2.1.176· 2026/06/13 · 2026/06/13

修复 claude --bg -cn <name> 组合不能正确设置会话名称的问题。

修复v2.1.160· 2026/06/02 · 2026/06/02

修复使用 `--bg` 时后台守护进程冷启动偶尔因 socket 缺失而失败

新增v2.1.154· 2026/05/29 · 2026/05/29

新增启动参数用于启用后台命令执行，与 --exec 配合运行 shell 命令

修复v2.1.153· 2026/05/28 · 2026/05/28

修复了即使升级后仍在过期守护程序上运行的问题

修复v2.1.142· 2026/05/15 · 2026/05/15

修复启动后台会话时的持久化问题

修复v2.1.140· 2026/05/13 · 2026/05/13

修复后台服务即将空闲退出时连接失败的问题