Appearance
Claude Code 的深度链接让你通过点击 claude-cli:// 格式的 URL，一键打开终端会话并自动进入指定仓库、预填提示文本。链接本身只填不执行，按回车后才发送。需要 Claude Code v2.1.91 或以上。用法包括用 repo 参数指向 GitHub 仓库名（自动匹配你最近用过且有记录的本地克隆），或用 cwd 指定绝对路径。在 macOS、Linux、Windows 上首次交互式启动时会自动注册 URL Handler。点击无反应时先确认是否启动过 claude，GitHub 渲染的 Markdown 不支持自定义协议，需要粘贴到浏览器地址栏解决。
Claude Code 深度链接配置：claude-cli:// 怎么用
从 URL 打开一个 Claude Code 终端会话。把
claude-cli://链接嵌入应急手册、告警、仪表盘里，点击就能在正确的仓库里打开 Claude Code，提示文本已经填好。
深度链接是一个 claude-cli:// 格式的 URL，会在新终端窗口里打开 Claude Code。URL 可以携带工作目录和预填的提示文本。这样你可以分享一个一键启动的任务入口：任何安装了 Claude Code 的人点击链接，就看到一个已经填好提示的会话——提示不会自动发送，需要你确认并按回车。
由于深度链接就是 URL，你可以把它放在任何能放链接的地方：
- 应急手册里的某个步骤，打开受影响服务的仓库并预填诊断提示
- 监控告警或仪表盘里，链接到针对某个指标的调查提示
- README 或 Wiki 页面上，用入职指引提示打开项目
- CI 失败通知里，预填失败 job 的名称
本页包含如何构建链接、嵌入应急手册或从命令行触发，以及在每个平台上管理或禁用注册。
深度链接需要 Claude Code v2.1.91 或更新版本。
工作原理
claude-cli:// 前缀是一个自定义 URL 协议，Claude Code 会把它注册到你的操作系统中，类似于 mailto: 链接打开邮件客户端。链接可以放在网页、Wiki、Slack 消息或任何能渲染链接的 App 中。点击链接后：
- 浏览器或 App 把 URL 交给操作系统。
- 操作系统识别到
claude-cli://前缀，启动你本机的 Claude Code。 - 新终端窗口打开，Claude Code 运行在链接指定的目录中，链接携带的提示文本已经出现在输入框里。
- 你阅读提示，可以编辑，然后按回车发送。
链接本身可以托管在任何地方，但会话始终在你点击链接的本地电脑上打开。具体每个操作系统打开哪个终端模拟器，请见注册与支持平台。
显示链接的平台必须允许自定义 URL 协议。GitHub 渲染的 Markdown 只允许
http和https，会剔除claude-cli://等协议——在 README、Issue、PR、Wiki 中，链接文本会显示，但实际没有链接，URL 被隐藏。解决方法见故障排除。
打开的会话显示什么
深度链接永远不会自己执行任何内容。链接只是选择一个目录并填好提示框。如果你点击了一个不信任的页面上的链接，提示仍然是静态的：只有在你阅读并按下回车后，内容才会发给模型。
会话打开时，输入框上方会显示一条横幅，说明会话是由外部链接启动的，以及它选择了哪个目录。如果提示超过 1000 个字符，横幅会提示你滚动查看完整文本后再按回车，因为长提示可能会把指令推出屏幕。权限规则、CLAUDE.md 以及所选目录的信任提示，与普通会话完全一致。
构建链接
所有深度链接都以 claude-cli://open 开头，这是处理器唯一接受的路径，后面可以跟可选的查询参数。最简形式是在你的家目录下打开 Claude Code，提示框为空：
text
claude-cli://open添加参数控制会话从哪里启动以及提示框的内容：
| 参数 | 描述 |
|---|---|
q | 预填到提示框的文本。需要对值进行 URL 编码。多行提示用 %0A 表示换行。最多 5000 个字符。 |
cwd | 用作工作目录的绝对路径。网络路径和 UNC 路径会被拒绝。 |
repo | GitHub 的 owner/name 格式。Claude Code 会解析为它之前见过的本地克隆，并在那里启动。如果没有匹配的克隆，会话会在家目录打开。 |
cwd 和 repo 是两种设置工作目录的方式。如果同时传递了两者，cwd 优先，即使 cwd 路径不存在，也会忽略 repo。
下面的链接指向名为 acme/payments 的仓库，并带有一个两行的诊断提示。构建你自己的链接时，把 acme/payments 替换为你的仓库 owner/name 格式：
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.点击后，会打开一个新终端窗口，Claude Code 启动在你的 acme/payments 本地克隆中，提示框填好了解码后的文本：
text
Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.你可以编辑提示后再按回车发送。如果没有该仓库的本地克隆，会话会在家目录打开。见在 cwd 和 repo 之间选择了解当你有多份克隆或 worktree 时如何选择本地路径。
在 cwd 和 repo 之间选择
当所有点击链接的人在相同绝对路径下有项目时（比如标准化的 devcontainer 或 VM 镜像），使用 cwd。
当链接是共享的，而且每个人克隆到不同位置时，使用 repo。Claude Code 按以下方式把 slug 解析为本地路径：
- 每次你在一个 Git 仓库里运行
claude时，该目录的文件系统路径会被记录到该仓库的 GitHubowner/name格式下。 - 当深度链接到达时，
repo会打开你最近使用过的那个匹配路径。多个克隆和 worktree 会分别跟踪，所以它选的是你最近工作过的那个。 - 查找只在至少运行过一次 Claude Code 的路径中生效。
- 链接不会改变当前 checkout 的分支。会话在仓库当前的任意状态下打开。
启动的会话会显示它选择了哪个路径，以及该克隆上次从远程拉取的日期，所以你能知道自己是否在看旧代码。
示例
下面展示两种常见用法：在文档中作为 Markdown 链接，以及在脚本或别名中作为命令打开。
在应急手册中嵌入链接
应急手册中的深度链接为值班人员提供了一键启动调查的方式：在正确的仓库，带着准备好的提示。渲染应急手册的平台必须允许自定义 URL 协议。GitHub 渲染的 Markdown 不允许 claude-cli://，所以 GitHub README、Issue 或 Wiki 中的深度链接只会显示标签，没有可点击的链接。解决方法见故障排除。
提示文本是 URL 的一部分，必须进行 URL 编码。在浏览器控制台或任何 URL 编码器中用 encodeURIComponent 处理你的提示文本。
下面的例子在名为 web-gateway 的服务应急手册中添加了一个调查入口点：
markdown
## High 5xx rate on web-gateway
1. Acknowledge the page in PagerDuty.
2. [Open Claude Code in the gateway repo](claude-cli://open?repo=acme/web-gateway&q=5xx%20rate%20is%20elevated%20on%20web-gateway.%20Check%20recent%20deploys%2C%20error%20logs%20from%20the%20last%2030%20minutes%2C%20and%20open%20incidents%20in%20Linear.)
3. Post initial findings in #incident.在你自己的应急手册中使用时，把 acme/web-gateway 替换为你服务的仓库 slug。这样安装了 Claude Code 且有该仓库本地克隆的工程师就可以点击步骤 2，用准备好的提示开始调查。
从命令行打开链接
你也可以通过 shell 脚本、别名或自动化工具打开深度链接，而不是通过点击。调用你操作系统的 URL 打开命令，把链接作为参数传入。
macOS
内置的 open 命令会把 URL 传给注册的 claude-cli:// 处理器：
bash
open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Linux
大多数桌面环境提供 xdg-open，会把 URL 传给注册的处理器：
bash
xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Windows PowerShell
PowerShell 的 Start-Process 会把 URL 传给注册的处理器：
powershell
Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Windows cmd.exe
start 会把它的第一个带引号参数当作窗口标题，所以 URL 前需要加一个空标题：
cmd
start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"注册与支持平台
Claude Code 在 macOS、Linux、Windows 上第一次启动交互式会话时，会自动向操作系统注册 claude-cli:// 处理器。不需要额外的安装命令。注册只写入用户级位置：
| 平台 | 处理器位置 |
|---|---|
| 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 |
处理器在检测到的终端模拟器中启动 Claude Code。在 macOS 上，Claude Code 会记住你最近交互式会话使用的终端，并复用。支持的终端包括 iTerm2、Ghostty、kitty、Alacritty、WezTerm 和 Terminal.app。在 Linux 上，优先级顺序是：$TERMINAL 环境变量、x-terminal-emulator、常用终端列表。在 Windows 上，优先使用 Windows Terminal，然后是 PowerShell，最后是 cmd.exe。
要完全阻止注册，在 settings.json 中将 disableDeepLinkRegistration 设置为 "disable"。要在整个组织中强制禁用且用户无法重新启用，请在托管设置中设置。
打开 VS Code 标签页而非终端
VS Code 扩展会注册它自己的处理器：vscode://anthropic.claude-code/open，打开的是一个 Claude Code 编辑器标签页，而不是终端窗口。相关 URL 参数请见从其他工具启动 VS Code 标签页。
故障排除
点击链接后什么也没发生
处理器很可能还没有注册。请在该机器上启动一次交互式 claude 会话，退出后再试一次链接。如果你在 Linux 上且没有桌面环境，xdg-open 可能没有可调度的处理器。
链接渲染成了纯文本，无法点击
部分 Markdown 渲染器只允许 http 和 https 链接，会剔除其他 URL 协议。GitHub 在 README、Issue、PR 和 Wiki 中就是这样：[label](claude-cli://...) 只会渲染为 label，没有链接，URL 被移除。在这些平台上，把深度链接放在代码块里，这样读者可以看到 URL 并粘贴到浏览器地址栏。
会话在家目录打开，而不是在指定仓库
repo 参数只能解析为 Claude Code 已经见过的克隆。请先在仓库内运行一次 claude，这样它的路径就会被记录下来；或者把链接改为使用带绝对路径的 cwd。
链接打开了错误的终端
在 macOS 上，先在你首选的终端里启动一次 claude，下一次深度链接就会使用它。在 Linux 上，设置 $TERMINAL 环境变量为你首选终端模拟器的命令名。在 Windows 上，顺序是固定的：如果你希望链接在 Windows Terminal 而不是 PowerShell 或 cmd.exe 窗口中打开，请安装 Windows Terminal。
了解更多
以下页面介绍了启动或扩展 Claude Code 会话的相关方式：
常见问题
在 VS Code 里能使用 claude-cli:// 深度链接吗？
可以，但 VS Code 扩展注册了它自己的处理器 vscode://anthropic.claude-code/open，打开的是编辑器标签页而非终端。你可以在应急手册或脚本中使用那个 URL 格式，参数与 claude-cli:// 类似，详见 VS Code 集成文档。
为什么我在 GitHub 仓库 README 里加了深度链接，点不了？
GitHub 渲染的 Markdown 只允许 http 和 https 协议，会剔除 claude-cli:// 链接。显示出来的只有标签文本，点击无效。解决方案：把完整的 URL 放在一个代码块中，让读者手动复制到浏览器地址栏打开。
点击链接后打开了家目录，我明明克隆过那个仓库啊？
repo 参数只匹配你至少运行过一次 claude 的目录。如果克隆后还没打开过 Claude Code，路径不会被记录。先在该仓库内运行一次 claude，之后深度链接就能正确打开。如果已经运行过仍然不匹配，改用带绝对路径的 cwd 参数。