Claude Code 的远程控制连不上：Remote Control 与 deep links 的两条链路
「我的 Claude Code 远程控制连不上」这句话，在群里问出来通常会得到一堆互相打架的答案。原因是它对应的其实是两条完全独立的链路，只是名字听起来都像「远程」：
- Remote Control：本机上跑着的 Claude Code 会话，被 claude.ai/code 或 Claude 手机 App 接管。会话仍在你的机器上执行。
- deep links：
claude-cli://这个自定义 URL scheme，点一下在本机开一个新终端窗口并预填 prompt。它不联任何远端会话。
两条链路的前置条件、失败点、判定动作完全不重叠。先分清自己卡在哪一条，再往下查，能省掉大半无用功。
先做一次分流
判定动作很简单，看你原本是怎么发起的：
- 你敲的是
claude remote-control、claude --remote-control，或在会话里敲/remote-control—— 走的是 Remote Control 链路。 - 你点的是一个
claude-cli://open?...链接，或在 shell 里调open/xdg-open/Start-Process—— 走的是 deep links 链路。
再补一条容易混的：官方文档专门写了 Remote Control 与 Claude Code on the web 的区别——前者在你的机器上执行，所以本地的 MCP 服务、工具和项目配置都还在；后者在云端执行。如果你的诉求是「本机根本没开机也要跑」，那两条链路都不解决问题。
还要先说清一件事：Remote Control 在官方文档里明确标注为 research preview（研究预览），且在 Team 与 Enterprise 计划上默认关闭，需要 Owner 在 Claude Code 管理设置里打开 Remote Control 开关。「文档写了」不等于「你这台机器现在就能用」。
链路一：Remote Control 连不上
现象
claude remote-control 直接报错退出；或者 claude --remote-control 起来了，会话能用，但启动后不久给出一条 Remote Control 失败通知。文档把这两种表现分开写了：没有合格登录时，claude remote-control 会带错误退出，而 claude --remote-control 仍会启动一个交互式会话，只是随后提示 Remote Control 失败。 所以「命令跑起来了」不等于远程链路建立了。
怎么确认是这个问题
先把文档列出的前置条件逐条对一遍，这几条都是可执行的检查：
- 登录方式。文档写明 API key 不被支持；先跑
claude再用/login通过 claude.ai 登录。若环境里设了ANTHROPIC_API_KEY，文档要求先把它 unset。 - API 端点。Remote Control 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 上不可用。文档还写明：自 v2.1.196 起，
ANTHROPIC_BASE_URL指向api.anthropic.com以外的主机（例如一个 LLM gateway 或代理）时，Remote Control 同样被禁用，需要把这个变量取消设置。 - feature-flag 评估。这一条最容易踩：
DISABLE_TELEMETRY、DO_NOT_TRACK、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_GROWTHBOOK这四个变量，任意一个都会关掉 Remote Control 可用性所依赖的 feature-flag 评估。文档特别提醒：不只是 shell 环境，settings.json的env块里设的也算。 - workspace trust。要先在项目目录里跑过一次
claude并接受 workspace trust 对话框。文档写明启动时的 trust 对话框从不会为你的 home 目录保存 trust，所以 Remote Control 要从项目目录里起。
然后按报错文案对号入座——文档的 Troubleshooting 一节是按错误原文分条组织的，照抄搜索比自己猜快：
| 错误文案（原文） | 文档给出的原因 |
|---|---|
Remote Control requires a claude.ai subscription | 没有用 claude.ai 账号认证 |
Remote Control requires a full-scope login token | 用的是 claude setup-token 或 CLAUDE_CODE_OAUTH_TOKEN 的长期 token，这类 token 只能发模型请求 |
Unable to determine your organization for Remote Control eligibility | 缓存的账号信息过期或不完整 |
Remote Control is not yet enabled for your account | 灰度未覆盖到你的账号，或缓存的权益过期 |
Couldn't verify Remote Control eligibility | 够不到 feature-flag 服务，通常是离线或代理拦截 |
Remote Control requires feature-flag evaluation | 上面那四个变量之一被设了，完整消息会点名是哪个 |
Remote Control is only available when using Claude via api.anthropic.com | 会话没有直连 Anthropic API |
Remote Control is disabled by your organization's policy | 消息里提到 disableRemoteControl 就是被管理设置禁掉；否则是 Owner 没开组织开关 |
Remote credentials fetch failed | 拿不到建立连接所需的短期凭据 |
文档语义给出的处置
- 前三条认证类问题，文档给的动作都是
claude auth login（权益过期那条要求先claude auth logout再 login）。 - 想知道具体是哪一项资格检查没过，文档指向
claude doctor。 - 凭据获取失败那条，文档给的动作是带
--verbose重跑看完整错误：
claude remote-control --verbose
文档列了这条错误的常见成因：未登录、防火墙或代理挡了出站 HTTPS（Remote Control 需要访问 Anthropic API 的 443 端口）、以及更早一步的会话创建失败（会伴随 Session creation failed — see debug log）。文档还澄清了一个反直觉的点：登录 token 过期不会导致这条错误，Claude Code 会自己刷新并重试；只有 v2.1.224 之前，过期 token 才会以这条消息让启动失败。
- 服务端回了本版本读不懂的响应（
Remote Control got an unexpected server response）时，文档说同版本重试会一样失败，动作是claude update之后再/remote-control。
处置后怎么验证
- 交互式会话里会有一个
/rc active指示器表示连接已建立；连接失败时它会切到失败状态并保留，可以再次调出失败原因。 - server mode 下
claude remote-control会显示一个 session URL，用它在任意浏览器打开就能直达会话；也可以在 claude.ai/code 或 Claude App 的会话列表里按名字找。 - 有一个隐蔽的验证技巧：文档写明 Claude Code 会在打印帮助前先检查 Remote Control 资格，所以没有合格账号时，
claude remote-control --help返回的是错误而不是 flag 列表。反过来说，--help能正常列出 flag，说明资格检查这一关过了。
什么情况说明不是这个原因
以下几种情况，文档明确归到别的机制，别再往「配置错了」的方向查：
- 失败原因里说会话被别处接管、被别处结束，或服务器找不到该会话。文档说这三种情形下 Claude Code 会刻意省掉平时那句「跑
/remote-control」的建议，因为重连意味着把会话从那台设备手里抢回来。这不是配置问题。 Remote Control isn't available for your organization due to its compliance policy。组织的数据留存/合规配置与 Remote Control 不兼容，管理面板里的开关是灰的，Owner 自己也改不动。文档还单独写明：有 Zero Data Retention 这类合规要求的组织不能启用 Remote Control。这类情况改环境变量没有用。- 本地进程已经不在了。文档把这一条列在 Limitations 里：Remote Control 是一个本地进程，关掉终端、退出 VS Code 或以任何方式停掉
claude进程，会话就会离线。要在 SSH 断开后仍保活，文档给的做法是把它放进tmux或screen里跑。 - 网络长时间不可达。文档区分了两种模式：server mode 会在持续够不到网络时放弃并让
claude remote-control进程退出，需要重新起；交互式会话则会一直重试，网络恢复后自行重连。前者进程没了不是「连不上」，是设计如此。 - 某些命令在手机和网页端本来就不工作。文档写明
/plugin、/resume这类只在终端界面运行的命令，无论是否带参数都只能从本地 CLI 用。你在手机上敲它没反应，不是链路故障。
另外，Trusted Devices 这套「必须先在设备上注册凭据才能查看或操控 Remote Control 会话」的机制，官方文档标注为 beta，只在 Team 与 Enterprise 计划上提供、默认关闭。报错是 Your organization requires Trusted Devices for Remote Control, but this device is not enrolled 时，文档给的动作是跑 /login——注册是登录流程的一部分，没有单独的注册命令。
链路二：deep link 点了没反应
现象
点 claude-cli://open?... 链接毫无动静；或者链接在页面上根本就不是个链接，只剩一段文字；或者终端确实开了，但开在 home 目录而不是你想要的仓库。
怎么确认是这个问题
deep link 的核心机制是 URL scheme 注册。文档写明：Claude Code 在你发送某个交互式会话的第一个 prompt 时才注册 claude-cli:// 处理器——启动 claude 然后不发 prompt 就退出，是不会注册的。没有单独的安装命令。
注册写入的都是用户级位置，可以直接去查：
| 平台 | 处理器位置 |
|---|---|
| macOS | ~/Applications/Claude Code URL Handler.app |
| Linux | $XDG_DATA_HOME/applications 下的 claude-code-url-handler.desktop，默认 ~/.local/share/applications |
| Windows | HKEY_CURRENT_USER\Software\Classes\claude-cli |
Windows 侧去注册表看那个键在不在，是最直接的判定动作。绕开浏览器直接从 shell 触发也能分离问题：
Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
cmd.exe 里要注意，start 会把第一个带引号的参数当成窗口标题，所以文档给的写法是先传一个空标题：
start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
macOS 用内置的 open，Linux 用 xdg-open，参数形式一致。上面例子里的 acme/payments 是官方文档中用来讲解语义的示例仓库 slug，换成你自己的 owner/name。
文档语义给出的处置
按现象分：
- 点了完全没反应：处理器多半还没注册。文档给的动作是在那台机器上起一个交互式
claude会话，发任意一个 prompt，退出，再试链接。 - Linux 上
xdg-open找不到：它属于xdg-utils包，文档点名精简服务器镜像、容器和 WSL 发行版经常不带它，动作是用发行版包管理器装上（文档给的例子是sudo apt install xdg-utils）。装完命令能跑但仍然什么都不开，文档说可能是xdg-open没有桌面环境可以分发。 - 链接渲染成纯文本：部分 Markdown 渲染器只放行
http和https，会剥掉其它 scheme。文档点名 GitHub 在 README、issue、PR、wiki 里就是这么做的，[label](claude-cli://...)只会渲染出label，链接和 URL 都没了。文档给的绕法是把 deep link 放进代码块，让读者自己复制到地址栏。 - 开在了 home 目录而不是仓库：
repo只解析 Claude Code 已经见过的 clone。文档描述的记录方式是：每次你在一个 Git 仓库里跑claude，Claude Code 就把该目录的路径记在这个仓库的 GitHubowner/nameslug 下；deep link 到达时打开你最近用过的那个匹配路径，多个 clone 与worktree分开跟踪。处置是「进那个 clone 里跑一次claude」，或者把链接换成带绝对路径的cwd。 - 开错了终端：macOS 上在你偏好的终端里起一次
claude，下次 deep link 就用它；Linux 上把$TERMINAL设成你想要的 emulator 的命令名。Windows 上文档写明顺序是固定的：优先 Windows Terminal，然后 PowerShell，然后cmd.exe——文档给的唯一办法是「想让链接开在 Windows Terminal 里就去装 Windows Terminal」，没有提到可调的配置项。
还有一个参数层面的坑：文档写明 cwd 与 repo 同时传时，cwd 优先、repo 被忽略，即使 cwd 指的路径根本不存在。此外 cwd 会拒绝网络路径与 UNC 路径，也拒绝含不可见字符或双向控制字符的路径——这条对 Windows 用户尤其相关，习惯性写 \\server\share\... 是过不去的。claude-cli://open 是处理器唯一接受的 path，参数只有 q、cwd、repo 三个，q 的值需要 URL 编码、多行用 %0A。
处置后怎么验证
- 文档写明欢迎信息里会显示它选中的路径，用来确认开对了 clone。
- 会话打开后会给出
Prompt from an external link的提示，在你发送或清空 prompt 前一直保留。看到它就说明 prompt 确实是从链接带进来的。 - 文档还明确了一个安全边界：deep link 自身不执行任何东西，它只选目录、填 prompt，不按 Enter 就什么都不会送到模型；权限规则、
CLAUDE.md和该目录的 trust 提示与普通会话一视同仁。这也意味着「链接打开了」不等于「任务跑了」。
什么情况说明不是这个原因
disableDeepLinkRegistration被设成"disable"。这是文档给的、彻底阻止注册的设置项，在settings.json里；放进受管设置（managed settings）后使用者无法自行开回来。这种情况下你再怎么发 prompt 也不会注册处理器，该去找管理员而不是继续折腾本机。- 你其实想要的是 VS Code 标签页。VS Code 扩展注册的是自己的处理器
vscode://anthropic.claude-code/open，打开的是 Claude Code 编辑器标签页而不是终端窗口。用claude-cli://去期待 VS Code 的行为，方向就错了。 - Linux 上没有桌面环境。文档写明这种情况下
xdg-open可能压根没有可分发的对象，这不是注册失败。 - 报错文案里出现的是 Remote Control 那一串。deep link 链路不产生那些消息。看到
Remote Control requires ...就说明你在查错链路，回到上一节。
两条链路唯一真正的交集
共同点只有一个：执行始终在你的本机。Remote Control 的文档写明本地会话只发出站 HTTPS 请求、从不在你的机器上打开入站端口，连接期间会话记录（你的消息、Claude 的回复和工具活动）存在 Anthropic 服务器上以便跨设备同步与断线重连，而执行与文件系统访问留在本机。deep link 则根本不涉及远端会话，链接可以托管在任何地方，会话总是在你点击的那台电脑上打开。
想彻底关掉，两条链路各有各的开关：Remote Control 用 disableRemoteControl，deep link 用 disableDeepLinkRegistration。文档把它们写成两个各自独立的设置项，分别落在各自那条链路上，没有写明存在联动关系。
最后提醒一句：上面引用的错误文案与行为，文档里大量带着「某某版本之前不是这样」的历史注记（比如 /remote-control 在 v2.1.206 之前未登录时报的是 Unknown command: /remote-control）。这类产品迭代频繁，你搜到的文案在你手上的版本里可能已经换了措辞，请以官方文档最新内容与 --help 的实际输出为准。
本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。
该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现；
我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。
该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。
本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。