Claude Code SDK #32：Deep Links 全解——claude-cli://open × repo × q，把 runbook 变成一键开工入口 (2026)

如果你的故障手册里还写着「打开仓库，然后把下面这段 prompt 复制进 Claude Code」，Deep Links 可以把这一步压成一个链接。

点击后，Claude Code 会在本机新开一个终端，进入指定项目，并把 prompt 预填到输入框里。注意，是预填，不是自动执行。你仍然要先读一遍，再按 Enter。1

这篇拆 claude-cli://open：它能解决什么、URL 怎么拼、cwd 和 repo 怎么选，以及为什么它适合放进 runbook、告警和内部 wiki。

1. Deep Links 解决的是「开工入口」问题

Deep Link 是一种 claude-cli:// URL。操作系统识别这个自定义协议后，会把链接交给 Claude Code 的本机 handler，Claude Code 再打开一个本地会话。官方把它定位为「从 URL 启动 Claude Code，并预填工作目录与 prompt」。1

它最适合四类场景：

故障手册：让值班工程师点一下就进入出问题的服务仓库，并看到排障 prompt。1
监控告警：把某个指标、服务名或失败 job 填进 prompt，减少临场复制信息的动作。1
README / wiki：给新同事一个 onboarding 入口，点击后直接打开项目上下文。1
CI 通知：把失败 job 名、最近提交、要检查的日志范围写进启动 prompt。1

Deep Links 要求 Claude Code v2.1.91 或更高版本。1 如果你在团队里推广，第一步不是写链接，而是先让大家确认版本和本机是否已经注册 handler。

2. 一个链接只做三件事

Deep Link 的最小形态是：

claude-cli://open

这会打开 Claude Code，默认进入用户 home 目录，prompt 为空。实际使用时，重点是三个 query 参数：

参数	作用	适合什么时候用
`q`	预填 prompt，需要 URL encode；多行 prompt 用 `%0A`；最大 5,000 字符。1	runbook、告警、CI 通知里已经知道要问什么
`cwd`	指定本机绝对路径作为工作目录；网络路径和 UNC 路径会被拒绝。1	团队有统一 devcontainer、VM 镜像或标准目录
`repo`	指定 GitHub `owner/name`。Claude Code 会解析成本机见过的 clone。1	每个人 clone 路径不同，但仓库 slug 相同

官方示例长这样：

claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.

这个链接会尝试打开本机的 acme/payments 仓库，并把两行诊断 prompt 填进输入框。1

这里有个容易踩坑的优先级：cwd 和 repo 都能设置工作目录；如果同时传入，cwd 优先，repo 会被忽略。即使 cwd 路径不存在，repo 也不会接管。1 团队模板里最好二选一，不要两个都塞。

3. `repo` 不是远程 clone，它只是在本机找路径

repo=owner/name 很像「让 Claude Code 打开 GitHub 仓库」，但它不会自动 clone，也不会切分支。

Claude Code 的规则更保守：每次你在一个 Git 仓库里运行 claude，它会把这个本机路径记录到对应的 GitHub owner/name slug 下。之后 deep link 带着 repo 进来时，它会选择最近使用过的匹配路径。多个 clone 和 worktree 会分别记录。1

这带来两个实践结论：

新人第一次使用前，要先在本机 clone 里跑一次 claude。否则链接会退回 home 目录。1
Deep Link 不改变当前分支。它打开的是那个目录当下的状态。1 如果 runbook 要求检查某个 release branch，prompt 里要明确写「先确认当前分支」或「切到指定分支前先询问」。

我更推荐团队共享链接时优先用 repo。cwd 看起来精确，但一换机器、一换用户名、一换 devcontainer 挂载路径就失效。repo 的失败方式更温和：找不到本地 clone 时会打开 home 目录，用户至少能看见 prompt，并知道自己少了本地准备。

4. 安全边界：预填不是执行

Deep Link 最大的安全设计是：链接不会自动把 prompt 发给模型。它只填进输入框，用户要自己按 Enter 才会发送。1

如果链接来自不可信页面，打开后仍然要检查 prompt。Claude Code 会在输入框下方显示 Prompt from an external link 警告；当 prompt 超过 1,000 字符时，警告还会显示字符数，并提醒你滚动查看全文。1

它也不会绕过现有项目边界。权限规则、CLAUDE.md 和工作目录 trust prompt 仍按普通会话生效。1

一个安全写法是把 prompt 写成「调查建议」，不要写成「立即执行」：

Review the recent CI failure for service web-gateway.
Before changing files, summarize the failure, list likely causes, and ask for confirmation.
Check logs from the last 30 minutes and recent commits to main.

Deep Link 负责把人带到正确起点，真正的执行控制仍然留在本机 Claude Code 会话里。

5. GitHub Markdown 会吞掉 `claude-cli://`

一个反直觉限制：GitHub 渲染的 README、issue、PR 和 wiki 不允许 claude-cli:// 这类自定义 URL scheme。你写 [Open Claude Code](claude-cli://...)，GitHub 会只显示文字，背后的链接会被移除。1

官方给的 workaround 是把 deep link 放进代码块，让读者复制到浏览器地址栏。1

所以，如果你的 runbook 放在 GitHub wiki，别指望它能一键点开。可以这样写：

Copy this link into your browser address bar:

claude-cli://open?repo=acme/web-gateway&q=Investigate%20the%20high%205xx%20rate.

Slack、Notion、Linear、内部工单系统是否保留自定义 scheme，要按平台实测。Deep Link 本身没问题，问题通常出在「展示链接的平台是否允许这种协议」。

6. 从脚本打开：把 Deep Link 当作本机启动器

Deep Links 不只能被点击，也可以从 shell、alias 或脚本里打开。官方列了三个系统入口：macOS 用 open，Linux 桌面环境通常用 xdg-open，Windows PowerShell 用 Start-Process。1

# macOS
open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

# Linux
xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

cmd.exe 有个小坑：start 会把第一个带引号的参数当窗口标题，所以要先传一个空标题。1

start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

这让 Deep Link 很适合做「本地辅助命令」。比如团队可以给每个服务生成一个 investigate-service alias：它读取当前服务名和告警 ID，拼出 URL encode 后的 prompt，再打开 Claude Code。

7. Handler 注册和关闭：别把这件事留到事故当天

Claude Code 会在 macOS、Linux、Windows 上第一次启动交互式会话时注册 claude-cli:// handler，不需要额外运行 install 命令。1

注册位置是用户级别：macOS 写到 ~/Applications/Claude Code URL Handler.app，Linux 写到 $XDG_DATA_HOME/applications 下的 desktop entry，Windows 写到 HKEY_CURRENT_USER\Software\Classes\claude-cli。1

终端选择也有平台差异：macOS 会复用最近一次交互会话使用的终端；Linux 先看 $TERMINAL，再看 x-terminal-emulator 和常见终端列表；Windows 优先 Windows Terminal，其次 PowerShell，再到 cmd.exe。1

如果组织不希望用户启用 Deep Links，可以在 settings.json 里把 disableDeepLinkRegistration 设为 "disable"；需要强制策略时，放到 managed settings。1

8. VS Code 不是同一个协议

如果你希望打开 VS Code 里的 Claude Code tab，而不是新终端窗口，协议不是 claude-cli://。Claude Code 的 VS Code extension 注册的是 vscode://anthropic.claude-code/open，会打开编辑器 tab。1

这两个入口最好分开命名：

claude-cli://open：给终端用户，适合本地 shell、runbook、告警排障。
vscode://anthropic.claude-code/open：给 IDE 用户，适合编辑器内工作流。

不要在同一篇文档里只写「Open Claude」，却不说会打开终端还是 VS Code。对一线排障的人来说，少一次界面猜测就是少一次中断。

今天就能照做的最小模板

如果只做一个模板，我会从 CI failure 开始。它足够具体，信息也容易自动拼出来：仓库、job 名、分支、失败时间和最近提交。

claude-cli://open?repo=OWNER/REPO&q=Investigate%20the%20CI%20failure%20for%20JOB_NAME.%0AFirst%20summarize%20the%20failing%20step%20and%20likely%20cause.%0AThen%20inspect%20recent%20commits%20and%20ask%20before%20editing%20files.

落地时按这个顺序检查：

团队成员的 Claude Code 版本不低于 v2.1.91。1
每个人在目标仓库里至少运行过一次 claude，让 repo 能解析到本机路径。1
选择能保留 claude-cli:// 的平台；如果平台会过滤自定义 scheme，就用代码块暴露 URL。1
prompt 写成可审阅的诊断指令，先总结、再定位、最后再请求是否修改。

Deep Links 的价值不在于「少复制一段文字」。它真正省掉的是事故现场最混乱的 30 秒：找仓库、找 prompt、确认上下文、想第一步问什么。把这 30 秒固定成一个链接，团队的 Claude Code 工作流就从「会用」往「能复用」前进了一小步。

Fuentes de referencia

1Launch sessions from links - Claude Code Docs