Claude Code 2.1.233: Linux Bash 进程内存上限功能上线

Claude Code 2.1.233: Linux Bash 进程内存上限功能上线 | 前端进阶之旅

Full translation

完整中文译文

Claude Code 2.1.233 通过 CLAUDE_CODE_TOOL_MEMORY_LIMIT 为 Linux 上的 Bash 工具命令新增了可选的 memory cgroup 支持。目标是隔离：如果某个构建、测试或搜索命令失控，子进程的工作负载应该撞上它自己的内存边界，而不是让整台机器和 Claude 会话变得无响应。

不要把这个设置当作会话级别的 RAM 上限。新边界只覆盖 Bash 工具命令进程，不影响 Claude Code 父进程、MCP 服务器、IDE、其他会话或所有子 agent 进程。先从一个临时会话来测试，从健康构建的内存数据来估算限制，并验证子进程确实进入了 claude-code-bash cgroup，同时保留主机层面的监控。

本指南面向在原生 Linux 或 WSL 上运行 Claude Code 的开发者，场景包括内存占用大的编译器、测试套件、包安装、静态分析或并行 agent 工作。在共享 runner 和 8–32 GB 开发机上尤其有用——任何一条异常命令都可能触发 swap 抖动或主机 OOM。

该设置不适用于 macOS 或 Windows，也不能替代子 agent 并发预算或托管 agent 支出上限：API 并发、token 费用和 Linux 进程内存是三条独立的限制。

发生了什么，边界意味着什么

Anthropic 的发布说明命名了这个环境变量，并说明它将 Linux Bash 工具命令置于 memory cgroup 之下。对 Anthropic 官方 2.1.233 Linux 包的实际检查给出了一份更精确的启动契约：

在 cgroup v2 上，memory.max 是一个硬限制。内核可能先回收内存；如果无法降低用量，cgroup OOM killer 可以终止该组内的进程。memory.events 记录了 max、oom 和 oom_kill，因此这些计数器比通用退出码更有力的证据。

根据证据选择限制值

在不启用新设置的情况下，运行相同的代表性构建或测试三次。记录峰值内存、时长、退出码和输出正确性。一个实用的起始规则是：

candidate limit = healthy peak × 1.5
host reserve    = max(2 GiB, 15% of host RAM)
final limit     = no higher than host RAM - host reserve

这是 IndieSeek 的推广经验法则，不是 Anthropic 的默认值。如果多个 Bash 命令或会话可能重叠，需要为它们合并的工作集做预算。四个并发会话各设 4 GiB 限制，仍然可能耗尽一台 16 GiB 的主机。

七步验收流程

升级一个 canary 主机并确认 claude --version 报告 2.1.233 或更高。保留之前的安装程序或版本回退路径。暂时不要改动所有登录 shell 或 runner 镜像。
验证 Linux 内存控制器

在 cgroup v2 主机上，在 Claude Code 之外运行以下检查：
```
uname -s
stat -fc %T /sys/fs/cgroup
grep -w memory /sys/fs/cgroup/cgroup.controllers
```
预期看到 Linux、cgroup2fs 以及可见的 memory 控制器。容器可能暴露 cgroup v2 但拒绝创建子 cgroup，所以这个预检是必要但不充分的。
启动一个有限制的会话

使用测量得到的候选值，而不是复制来的通用数字：
```
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4GiB claude
```
官方包接受 4G、4GB 和 4GiB 作为二进制单位形式。在 canary 阶段将该值保持为会话本地。
证明 cgroup 成员资格和解析后的限制

让 Claude 运行这条无害的 Bash 命令：
```
set -eu
cg_rel=$(awk -F: '$1 == "0" { print $3 }' /proc/self/cgroup)
cg_dir="/sys/fs/cgroup${cg_rel}"
printf 'cgroup=%s\n' "$cg_rel"
printf 'memory.max=' && cat "$cg_dir/memory.max"
printf 'memory.current=' && cat "$cg_dir/memory.current"
cat "$cg_dir/memory.events"
```
要求 cgroup 路径以 claude-code-bash 结尾，且 memory.max 与预期的字节数匹配。对于 4GiB，应该是 4294967296。如果任一检查失败，停止：环境变量存在，但隔离未得到证明。
运行正向对照

运行正常的构建、测试和一个搜索密集型任务。要求输出正确、时长可接受、Claude 会话保持响应，且 oom_kill 不增加。如果普通工作被杀死，说明限制太低或工作负载需要不同的通道。
运行一个一次性失败 canary

仅在临时 VM 或隔离的 runner 上，使用一个非敏感程序以固定块大小分配内存，直到 cgroup 将其杀死。不要在生产主机上运行故意 OOM。失败后验证：
- memory.events 的 oom 或 oom_kill 有增量。
- shell 命令明确失败，而不是无限挂起。
- 之后 Claude 能执行新的无害 Bash 命令。
- 主机、终端和无关服务保持响应。
这证明了隔离和恢复。被杀死的子进程如果会话没有存活下来，不能算作通过的结果。
每次推广一个工作负载类别

先推广构建，然后测试，然后更重的并行工作。保持并发分别受限，并采样 memory.current、memory.events、主机可用 RAM 和 swap。通过移除变量或设置为 none，然后重启 Claude Code 来回滚。

决策树

Is the host Linux/WSL with a usable memory cgroup?
  no  -> keep host-level isolation; do not claim this setting works
  yes -> does a Bash child enter claude-code-bash with the expected memory.max?
           no  -> stop and fix delegation or permissions
           yes -> does the normal workload pass below the limit?
                    no  -> raise the evidence-based limit or split the workload
                    yes -> does the disposable OOM canary kill only the child?
                             no  -> keep the feature canary-only
                             yes -> promote one workload class and monitor events

常见误区

将限制设为一次观察到的峰值而不留波动余量。
假设该限制覆盖了 Claude Code、MCP 服务器、IDE 和所有子 agent。
只检查导出的变量而不验证 cgroup 成员资格和 memory.max。
在笔记本或生产 runner 上运行故意 OOM 测试。
增加会话并发而不将限制值相加。
将每个被杀死的构建都视为产品 bug，而不是区分真正的内存泄漏和限制过小。

可复制的推广记录模板

date / owner / host / kernel / WSL-or-native:
claude_version / install_source:
cgroup_version / memory_controller / delegation_result:
healthy_task / run_count / peak_memory / duration / exit_result:
configured_value / resolved_memory.max / cgroup_path:
positive_control / output / duration / memory.events_delta:
disposable_oom_canary / child_result / session_recovery / host_health:
concurrent_sessions / aggregate_budget / host_reserve:
decision: hold | raise-limit | limited-rollout | promote | rollback
rollback_value / restart_proof:

常见问题

我应该把 CLAUDE_CODE_TOOL_MEMORY_LIMIT 设成多少？

没有通用数字。测量一个代表性的健康工作负载，加上波动余量，为操作系统和非 Bash 进程预留内存，并考虑并发会话。先在一台主机上试点。

这个限制能阻止 Claude Code 本身使用过多内存吗？

不能。2.1.233 版本的发布说明描述的是 Bash 工具命令的 cgroup 支持。对于 Claude Code 进程本身的高内存，使用 Anthropic 的 /compact、安全模式、重启和 /heapdump 故障排除路径；永远不要发布堆快照，因为它可能包含对话内容和凭据。

被 OOM 杀死的 Bash 命令算是成功的测试吗？

只有在以下条件下才算：在一次性环境中运行、memory.events 证明了 cgroup OOM、Claude 会话恢复、主机保持健康。目标是受控失败，不仅仅是进程死亡。

参考链接

Anthropic: Claude Code v2.1.233 release

Anthropic: official Claude Code 2.1.233 package

Anthropic: Claude Code performance and memory troubleshooting

Linux kernel: cgroup v2 memory controller