Claude Code 走 Headroom 代理后 Remote Control 菜单消失怎么处理

如果你把 Claude Code 通过 Headroom 代理（即 ANTHROPIC_BASE_URL 指向 Headroom 的本地代理地址，例如 http://127.0.0.1:8787，headroom wrap claude 就是这么做的），会发现 Claude Code 里的 Remote Control 菜单不见了，/remote-control（/rc）命令也调不出来。这个问题在 Claude Code 2.1.196 及以上版本是确定性的客户端行为，不是 Headroom 的 bug，代理侧无法把它恢复回来。本文说明如何确认自己是否命中这个限制，以及按官方给出的方式处理：普通压缩会话继续走 Headroom，需要 Remote Control 的会话改直连。

适用前提（来自项目文档）：

• Claude Code 版本在 2.1.196 及以上（或版本检测失败，文档按"未知版本同样可能受影响"处理）；
• 会话是订阅制（Pro/Max 订阅）。如果你配置了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN（按量付费）或 CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX / CLAUDE_CODE_USE_FOUNDRY（云 IAM），这类会话本来就没有 Remote Control，不会出现"菜单消失"的问题，Headroom 的警告也不会为它们触发。

为什么代理侧修不好：这是一个 Claude 客户端门禁

Claude Code 2.1.196 增加了一个客户端资格检查：只要 ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主机，就会禁用第一方 Remote Control（/remote-control / /rc）。这个命令把本地 CLI 会话镜像到 claude.ai/code 和移动端，而它的控制面是跟 claude.ai 通信，不经过 API 主机——所以请求根本不会到达 Headroom，Headroom 只收到并压缩普通的 API 流量，没有任何端点可以"代转"来绕过这个判断。

这正是项目文档中 Remote Control unavailable through custom ANTHROPIC_BASE_URL 一节的结论：

Fix: Use Headroom for normal proxied API sessions, and launch Claude directly (without ANTHROPIC_BASE_URL) when you need Claude Remote Control.

判断"自定义端点"只看主机名是否等于 api.anthropic.com（见 is_custom_anthropic_base_url）：方案、端口、路径都忽略，http://127.0.0.1:8787 这种 Headroom 代理地址必然命中门禁。同一机制还覆盖了旧版本边界：Claude Code 低于 2.1.196 的构建上，Remote Control 不受自定义 base URL 影响，Headroom 不会发出这条警告（见 remote_control_gate_active）。

确认你的会话是否命中门禁

按下面顺序核对，三项都满足时菜单消失就是这个门禁导致的，而不是配置错误。

1. 看 Claude Code 版本。 claude --version 输出形如 2.1.196 (Claude Code)（文档示例），2.1.196 及以上才会被门禁。

2. 看认证方式。 如果环境里有非空的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或三个云 IAM 变量（CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY），说明该会话从未有过 Remote Control，菜单缺失与代理无关，可以跳过本文的后续处理。

3. 用 headroom doctor 复核。 doctor 内置了名为 claude remote control 的检查项（check_claude_remote_control_gate），它同时检查 shell 环境里的 ANTHROPIC_BASE_URL 和 ~/.claude/settings.json 中 env 块里的值（shell 优先），并自动调用 claude --version 解析版本。命中门禁时输出 WARN，措辞为（英文原文，端点来源处按实际情况显示 in shell 或 from settings）：

Remote Control: Claude Code 2.1.196 disables the /remote-control (/rc) command
while ANTHROPIC_BASE_URL points at a custom endpoint (...). Headroom cannot
override this client-side gate — run Claude without Headroom for sessions that
need Remote Control.

同一条提示还会附带一行 sibling gate 说明，指出同一个 base URL 门禁同时影响按需工具加载（#746，headroom wrap claude 默认保持开启）和 1M 上下文窗口（#1158，用 headroom wrap claude --1m 开启）——这两项与 Remote Control 不同，Headroom 是能恢复的。

如果你平时是通过 headroom wrap claude 启动 Claude Code，启动横幅里也会打印同样的警告（见 wrap.py 中的门禁提示逻辑）。反过来，如果 doctor 没有报出 claude remote control 这一行，说明当前环境不满足门禁条件（直连、API-key/云认证，或版本低于 2.1.196）。

处理方式：按用途拆成两种会话

文档给出的处理方式只有一个，就是让两种用途走不同的启动方式：

普通编码会话——继续走 Headroom。 压缩、ENABLE_TOOL_SEARCH 的上下文节省照常生效。文档明确说明 ENABLE_TOOL_SEARCH 不受 Remote Control 门禁影响，走代理时可以保持开启：

# 走代理的常规会话（ENABLE_TOOL_SEARCH 保持可用）
headroom wrap claude

# 需要 1M 上下文时
headroom wrap claude --1m

需要 Remote Control 的会话——不带 ANTHROPIC_BASE_URL 直连启动：

# 确保 shell 中没有导出 ANTHROPIC_BASE_URL，直接启动
claude

注意 doctor 检查的是两处来源：shell 环境变量和 ~/.claude/settings.json 的 env 块。如果之前用 headroom wrap claude 包裹过，base URL 可能已被写入 settings 文件；要"直连"，就得保证两处都不再指向 Headroom 代理，否则门禁依旧生效。

处理后的核对方式：直连会话里 /rc 命令重新可用，即说明该会话脱离了门禁；再跑一次 headroom doctor，claude remote control 检查项不再出现 WARN（因为环境里已经没有自定义 base URL）。

边界与常见误判

• 不要期待代理侧参数能恢复菜单。 文档结论是 "Headroom cannot override this client-side gate"，这是 Claude 侧有意为之的安全边界（同类门禁还有 server-managed settings，同样要求直连 api.anthropic.com）。
• 旧版本不是"没修好"。 低于 2.1.196 的构建上，自定义 base URL 本来就不禁用 Remote Control；如果你在这个版本以下也看不到菜单，原因不在这个门禁里，项目文档没有给出其他排查路径。
• API-key / 云 IAM 用户本来就没有 Remote Control。 Remote Control 是 claude.ai 订阅会话的功能，按量付费和 Bedrock/Vertex/Foundry 会话从未出现过 /rc 命令，菜单缺失不是"被代理弄丢的"。

一句话总结：菜单消失是 Claude Code 2.1.196+ 在自定义 ANTHROPIC_BASE_URL 下的确定性行为，确认方式看 claude --version、认证方式和 headroom doctor 的 claude remote control 检查项；处理方式就是压缩会话继续 headroom wrap claude，Remote Control 会话去掉 ANTHROPIC_BASE_URL 直连启动。