Claude Code SDK #40：Deep Links 全解——claude-cli:// × repo × q，把 runbook 变成一键启动会话

Claude Code SDK #40：Deep Links 全解——claude-cli:// × repo × q，把 runbook 变成一键启动会话

Deep Links 让 runbook、告警和 onboarding 文档用一个 claude-cli:// 链接打开本机 Claude Code 会话，并预填目录与 prompt。本篇拆解 q、cwd、repo 参数、安全边界、GitHub 渲染限制和 VS Code handler，帮助开发者把重复排查流程做成可点击入口。

Claude Code SDK 每日技术拆解
Claude Code SDK 每日技术拆解@wei
Deep Link 最适合解决一个很小但很烦的问题：故障来了、CI 挂了、同事刚进项目，你不想再发一段「先 cd 到哪个目录，再把这段 prompt 复制进去」的说明。一个 claude-cli://open?... 链接，就能把人带到本机的 Claude Code 会话里，目录和提示词都先放好；但它不会替你自动执行，Enter 仍然在你手里。1

1. Deep Link 到底打开了什么

Deep Link 是 Claude Code 注册到操作系统里的自定义 URL scheme，前缀是 claude-cli://，效果类似 mailto: 打开邮件客户端。点击链接后，浏览器或聊天工具把 URL 交给操作系统，系统识别这个 scheme，然后在本机启动 Claude Code。1
这里有两个边界要先记住：
  • 会话始终在点击链接的那台电脑上打开，不是在生成链接的服务器上打开。1
  • 链接只负责选择工作目录、预填 prompt；prompt 不会自动发给模型，用户读完后按 Enter 才会发送。1
这点很关键。Deep Link 不是「远程控制 Claude Code」，更像一个可点击的任务入口。它把上下文放到正确位置，把第一句话写好，然后把最终确认权留给操作者。

2. URL 结构：只接受 open，参数主要看三个

最小链接长这样：
claude-cli://open
官方文档说明，handler 只接受 claude-cli://open 这个路径，后面可以跟查询参数。q 是预填到 prompt 框里的文本，必须 URL encode，多行 prompt 可以用 %0A 表示换行，最长 5,000 字符；cwd 是绝对路径；repo 是 GitHub 的 owner/name 仓库 slug。1
一个排查支付服务发布失败的链接可以写成：
claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.
点开后，Claude Code 会尝试进入本机的 acme/payments clone，并把解码后的两行 prompt 放进输入框。没有匹配的本地 clone 时，会话退回到 home directory。1

3. cwd 和 repo 的选择，不是风格问题

如果你的团队使用统一路径，例如 devcontainer、云桌面或标准 VM 镜像，cwd 很直接：大家的项目都在同一个绝对路径，链接就写这个路径。官方同时限制了 cwd：网络路径、UNC 路径，以及包含不可见或双向控制字符的路径会被拒绝。1
如果链接要发给不同机器上的开发者，优先用 repo。Claude Code 会把你运行过 claude 的 Git 仓库路径记录到对应的 GitHub owner/name slug；同一个仓库有多个 clone 或 worktree 时，它会选最近使用过的那个路径。1
要注意两个坑：
场景实际行为
同时传 cwd 和 repocwd 优先，repo 会被忽略；即使 cwd 不存在，也仍然以 cwd 为准。1
本机从没在这个 clone 里运行过 Claude Coderepo 查不到路径，会话打开到 home directory。1
所以团队共享链接时，repo 更稳；个人脚本、固定环境和一次性本地自动化，cwd 更省事。

4. 安全模型：它会预填，但不会偷跑

Deep Link 最容易被误解成「点一下就执行 prompt」。官方文档说得很明确：它不会自己执行任何东西。会话打开后，输入框下方会显示 Prompt from an external link 警告；如果 prompt 超过 1,000 字符，警告还会提示字符数，并要求你滚动检查完整文本。1
权限规则、CLAUDE.md、目标目录的 trust prompt 仍然按普通 Claude Code 会话生效。换句话说，Deep Link 没有绕过权限系统，它只是把「进入哪个目录、先问什么」这两步变成链接。1
如果团队不希望机器注册这个 URL handler，可以在 settings.json 里把 disableDeepLinkRegistration 设为 "disable"；组织级禁用则放进 managed settings。1

5. 最适合放在哪里

Deep Link 的强项不是日常闲聊，而是把「重复发生的工程场景」变成可复用入口。
几个适合直接落地的位置：
  • 事故 runbook：某服务 5xx 率升高时，链接直接打开对应 repo，并预填「检查最近部署、日志和未关闭 incident」这类诊断 prompt。1
  • 监控告警或 dashboard：某个指标异常时，把服务名、指标名和排查窗口写进 q 参数，让值班同学少复制一段上下文。1
  • README / wiki onboarding：新人点开链接后，Claude Code 进入本地 clone，并先问「解释这个项目的启动路径和核心模块」。1
  • CI 失败通知：把失败 job 名称塞进 prompt，让开发者从通知直接进入排查。1
但有一个现实限制：渲染链接的平台必须允许自定义 URL scheme。GitHub 渲染的 README、issue、PR 和 wiki 会剥掉 claude-cli:// 这类 scheme，只留下不可点击的文本；官方建议在这些地方把 Deep Link 放进代码块，让读者复制到浏览器地址栏。1

6. 终端、VS Code 和脚本各走哪条路

普通 Deep Link 打开的是终端里的 Claude Code。Claude Code 第一次启动交互会话时，会在 macOS、Linux 和 Windows 上注册 claude-cli:// handler；macOS 会复用最近一次交互会话使用的终端，Linux 会按 $TERMINAL、x-terminal-emulator 和常见终端列表查找，Windows 优先使用 Windows Terminal，然后是 PowerShell 和 cmd.exe。1
如果你想从脚本触发，调用系统的 URL opener 就行：macOS 用 open，Linux 用 xdg-open，PowerShell 用 Start-Process，cmd.exe 则要先传一个空窗口标题。1
如果目标是打开 VS Code 里的 Claude Code tab，而不是终端窗口，要换成 VS Code 扩展自己的 handler：vscode://anthropic.claude-code/open。这个 handler 支持 prompt 预填文本，也支持用 session 恢复某个属于当前 workspace 的会话。2

7. 我的建议：把 prompt 写短，把长流程交给 Skill 或文档

q 的上限是 5,000 字符，但这不代表应该把整份 runbook 都塞进 URL。长 prompt 会增加审阅成本，也更容易在聊天工具、文档渲染或手动复制时出问题。
更稳的做法是：Deep Link 只写「任务入口」和少量变量，详细操作留在仓库里的 runbook、CLAUDE.md 或 Skill 中。官方也在 Learn more 里建议，可以把长 runbook prompt 存成 repo 里的 /skill，Deep Link 的 q 只需要点名调用它。1
一个可直接尝试的最小模板：
claude-cli://open?repo=YOUR_ORG/YOUR_REPO&q=Open%20CLAUDE.md%20and%20run%20the%20incident%20triage%20checklist%20for%20SERVICE_NAME.%20Summarize%20the%20first%203%20findings%20before%20editing%20files.
把 YOUR_ORG/YOUR_REPO 和 SERVICE_NAME 换掉，再放到内部 runbook 或告警通知里。第一次使用前，让团队成员在对应 clone 里运行一次 claude，否则 repo 找不到本地路径。
Deep Link 的价值不在炫技，而在少一次上下文丢失。事故、CI、onboarding 这些场景里，开发者最怕的不是多按一个按钮，而是临场忘了从哪里查起。把入口做成链接，至少可以让第一步不再靠记忆。

참고 출처

  1. 1Launch sessions from links - Claude Code Docs
  2. 2Use Claude Code in VS Code - Claude Code Docs

관련 콘텐츠

  • 로그인하면 댓글을 작성할 수 있습니다.
More from this channel
View the full content archive of "Claude Code SDK 每日技术拆解"Explore more channels on Discover