Claude Code 深度学习手册

主题

Deep Links 深链接 ​

用 claude-cli:// URL 一键打开 Claude Code 会话并预填目录与提示词。

是什么 ​

Deep Link（深链接）是一种 claude-cli:// 协议的 URL，点击后会在新的终端窗口打开 Claude Code。该 URL 可携带工作目录和一段预填到输入框的提示词，从而为某项任务提供一键起点：任何安装了 Claude Code 的人点击链接，就会看到会话打开、提示词已经输入好（已填入但不会自动发送，需按 Enter 才发送）。

由于它本质是一个 URL，可放在任何能放链接的地方，例如事故 runbook 步骤、监控告警/仪表盘、README/wiki 的上手提示，或 CI 失败通知中预填失败任务名。

怎么工作 ​

  • claude-cli:// 是 Claude Code 向操作系统注册的自定义 URL scheme，类似 mailto: 打开邮件客户端。
  • 点击流程：浏览器/应用把 URL 交给操作系统 → 系统识别 claude-cli:// 前缀并在本机启动 Claude Code → 打开新终端窗口，在链接指定目录运行，提示词已填入输入框 → 用户审阅、可编辑，按 Enter 发送。
  • 链接可托管在任何地方，但会话始终在你点击的那台本机本地打开。
  • 深链接本身永不自动执行任何内容：它只选择目录并填充提示框，在按 Enter 之前没有任何内容会发给模型。
  • 会话打开时，输入框上方会显示横幅，提示是由外部链接启动以及选中了哪个目录；当提示词超过 1,000 字符时，横幅会提醒滚动审阅全文再按 Enter。
  • 选定目录的权限规则、CLAUDE.md 和信任提示与普通会话一样生效。

怎么配置 / 用法 ​

每个深链接都以 claude-cli://open 开头（handler 只接受这一个 path），后接可选查询参数。最小形式在 home 目录打开、提示为空：

text
claude-cli://open

参数：

  • q：预填到提示框的文本，需 URL 编码（encodeURIComponent），多行用 %0A 表示换行，最多 5,000 字符。
  • cwd：作为工作目录的绝对路径，拒绝 network/UNC 路径。
  • repo：GitHub owner/name slug，Claude Code 解析为它见过的本地克隆并在那里启动；无匹配克隆则在 home 目录打开。
  • 同时传 cwd 和 repo 时，cwd 优先，repo 被忽略（即使 cwd 路径不存在）。

示例（指向 acme/payments，带两行诊断提示）：

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

从 shell 打开：

bash
# 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"
powershell
# Windows PowerShell
Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"

什么时候用 ​

  • 事故 runbook 步骤：一键在受影响服务的仓库打开并预填诊断提示。
  • 监控告警或仪表盘：链接到针对某指标的调查提示。
  • README/wiki：打开项目并预填上手 onboarding 提示。
  • CI 失败通知：预填失败任务名作为提示。
  • 团队共享任务起点：所有装了 Claude Code 的人点击即可带着准备好的提示词开始。

限制 / 坑 ​

  • 需要 Claude Code v2.1.91 或更高版本。
  • 展示链接的平台必须允许自定义 URL scheme；GitHub 渲染的 Markdown（README/issue/PR/wiki）只允许 http/https，会剥离 claude-cli://，只显示链接文字（变通：放进代码块让读者复制到地址栏）。
  • repo 只能解析到 Claude Code 已经见过（至少运行过一次 claude）的本地克隆路径，否则会退回 home 目录；链接不会改变检出的分支。
  • cwd 拒绝 network 和 UNC 路径。
  • 若 handler 尚未注册，点击无反应——需先在该机器上启动一次交互式 claude 会话；无桌面环境的 Linux 上 xdg-open 可能无处分派。

硬事实速查（11 条） ​

  • URL scheme 为 claude-cli://，唯一接受的 path 是 claude-cli://open。
  • 三个查询参数：q（提示文本，URL 编码，%0A 换行，最多 5,000 字符）、cwd（绝对路径，拒绝 network/UNC）、repo（GitHub owner/name slug）。
  • cwd 与 repo 同传时 cwd 优先，repo 被忽略。
  • 提示词只填入不自动发送，需按 Enter；超过 1,000 字符时横幅提醒滚动审阅。
  • 需要 Claude Code v2.1.91 或更高版本。
  • 首次在 macOS/Linux/Windows 启动交互式会话时自动注册 handler，无需单独安装命令，仅写入用户级位置。
  • Handler 位置：macOS ~/Applications/Claude Code URL Handler.app；Linux claude-code-url-handler.desktop（位于 $XDG_DATA_HOME/applications，默认 ~/.local/share/applications）；Windows HKEY_CURRENT_USER\Software\Classes\claude-cli。
  • 终端选择：macOS 复用最近一次交互会话的终端（支持 iTerm2、Ghostty、kitty、Alacritty、WezTerm、Terminal.app）；Linux 依次看 $TERMINAL、x-terminal-emulator、常见 emulator 列表；Windows 顺序固定为 Windows Terminal → PowerShell → cmd.exe。
  • 用 disableDeepLinkRegistration 设为 "disable" 可禁用注册；在 managed settings 中设置可全组织强制。
  • VS Code 扩展注册自己的 handler vscode://anthropic.claude-code/open，打开编辑器标签页而非终端。
  • repo 记录每次在 Git 仓库运行 claude 的路径，按最近使用的匹配路径打开，多个克隆和 worktree 分别跟踪。

官方出处：https://code.claude.com/docs/en/deep-links