通过链接启动会话

从一个网址打开一个 Claude Code 终端会话。在运行手册、告警和仪表盘中嵌入 claude-cli:// 链接，让点击就能在正确的仓库中打开带正确提示词的 Claude Code。

一个深层链接是一个能在新终端窗口中打开 Claude Code 的 claude-cli:// 网址。该网址可以携带一个工作目录和一个预填的提示词。

这让你可以分享一个任务的一键起点：任何安装了 Claude Code 的人点击该链接，就会看到一个已经打好提示词的会话被打开。该提示词只是被填入，不会自动发送，直到你按下 Enter。

由于深层链接就是一个网址，你可以把它放在任何能放链接的地方：

• 在一个事故运行手册的某一步中，打开受影响服务的仓库，并带一个诊断提示词
• 在一个监控告警或仪表盘中，链接到针对某个特定指标的调查提示词
• 在一个 README 或 wiki 页面中，打开该项目并带一个入职提示词
• 在一个 CI 失败通知中，预填失败任务的名称

本页介绍如何构建一个链接、在运行手册中嵌入它，或从 shell 触发它，以及在各平台上管理或禁用处理程序注册。

工作原理

claude-cli:// 前缀是一个自定义网址方案，由 Claude Code 向你的操作系统注册，类似于 mailto: 链接会打开你的邮件客户端。这个链接可以存在于一个网页、一份 wiki、一条 Slack 消息，或任何能渲染链接的应用中。当你点击它时：

1. 浏览器或应用把该网址交给你的操作系统。
2. 操作系统识别出 claude-cli:// 前缀，并在你的机器上启动 Claude Code。
3. 一个新的终端窗口打开，Claude Code 运行在该链接指定的目录中，输入框中已经有了该链接的提示词文本。
4. 你阅读该提示词，如果需要可以编辑它，按下 Enter 发送它。

该链接本身可以托管在任何地方，但会话总是在你点击它所在的那台计算机上本地打开。关于各操作系统上会打开哪种终端模拟器，请参阅注册与支持的平台。

启动的会话会显示什么

一个深层链接本身绝不会执行任何操作。该链接只会选择一个目录并填充提示词输入框。如果你点击了一个来自不信任页面的链接，该提示词仍然是无害的：在你阅读被填入的内容并按下 Enter 之前，什么都不会到达模型。

会话打开时，输入框下方会显示一行警告，写着 Prompt from an external link，并保持可见，直到你发送或清空该提示词。对于超过 1,000 个字符的提示词，该警告会包含字符数，并告诉你在按下 Enter 之前滚动查看完整文本，因为长提示词可能会把指令推出屏幕之外。所选目录的权限规则、CLAUDE.md 和信任提示，与其他任何会话一样正常适用。

构建一个链接

每个深层链接都以 claude-cli://open 开头（这是该处理程序唯一接受的路径），后面跟着可选的查询参数。最简形式会在你的主目录中打开 Claude Code，提示词为空：

claude-cli://open

添加参数可以控制会话从哪里开始，以及提示词输入框中包含什么：

cwd 和 repo 是设置工作目录的两种方式。如果你同时传入两者，cwd 优先，repo 会被忽略，即使 cwd 路径不存在也是如此。

以下链接指向一个名为 acme/payments 的仓库，带一个两行的诊断提示词。构建你自己的链接时，请把 acme/payments 替换为你仓库的 owner/name 标识：

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 的克隆中启动 Claude Code，并用解码后的文本填充提示词输入框：

Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.

按下 Enter 发送之前，你可以编辑该提示词。如果你没有该仓库的本地克隆，该会话会改为在你的主目录中打开。关于当你有多个克隆或 worktree 时如何选择本地路径，请参阅在 cwd 和 repo 之间选择。

在 cwd 和 repo 之间选择

当点击该链接的每个人都把该项目放在同一个绝对路径下时（例如一个标准化的 devcontainer 或 VM 镜像），使用 cwd。

当该链接被分享给多人、每个人克隆到不同位置时，使用 repo。Claude Code 会按以下方式将该标识解析为一个本地路径：

• 每次你在一个 Git 仓库中运行 claude，该目录的文件系统路径都会被记录在该仓库 GitHub 的 owner/name 标识下。
• 当一个深层链接到达时，repo 会打开你最近使用过的匹配路径。多个克隆和 worktree 会分别被追踪，因此它会选择你最后一次工作过的那个。
• 这个查找只会找到你已经至少运行过一次 Claude Code 的路径。
• 该链接不会改变检出的是哪个分支。会话会以该目录当前所处的状态打开。

欢迎消息头部会显示它选择了哪个路径，方便你确认打开的是正确的克隆。

示例

以下小节展示了使用深层链接的两种常见方式：作为文档中的一个 Markdown 链接，以及作为脚本或 shell 别名中的一条命令。

在运行手册中嵌入一个链接

运行手册中的深层链接，为负责处理问题的人提供了一个一键式的方式，让他们能在正确的仓库中、带着准备好的提示词开始调查。渲染该运行手册的平台必须允许自定义网址方案。GitHub 渲染的 Markdown 不允许 claude-cli://，因此 GitHub README、issue 或 wiki 中的深层链接只会显示其标签，没有可点击的链接。关于变通方法，请参阅故障排查说明。

该提示词是网址的一部分，必须进行网址编码。要生成编码后的值，可以在浏览器控制台中或任意网址编码工具中，把你的提示词文本传给 encodeURIComponent。

以下示例为一个名为 web-gateway 的服务的事故运行手册添加了一个调查入口：

## 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 替换为你服务的仓库标识。这让安装了 Claude Code、且拥有该仓库本地克隆的工程师，能点击第 2 步，用已经准备好待发送的提示词开始调查。

从 shell 打开一个链接

除了点击之外，你也可以从一个 shell 脚本、别名或自动化流程中打开一个深层链接。用你操作系统的网址打开命令，把该链接作为参数调用。

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

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

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

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

注册与支持的平台

在 macOS、Linux 和 Windows 上，你第一次启动一个交互式会话时，Claude Code 会向你的操作系统注册 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 编辑器标签页，而不是终端窗口。关于该网址的参数，请参阅从其他工具启动一个 VS Code 标签页。

故障排查

点击该链接没有任何反应

该处理程序很可能尚未注册。在那台机器上启动一次交互式 claude 会话，退出，再试一次该链接。如果你在没有桌面环境的 Linux 上，xdg-open 可能没有可分发的目标。

该链接渲染为纯文本，而不是可点击的

有些 Markdown 渲染器只允许 http 和 https 链接，会剥离其他网址方案。GitHub 在 README、issue、pull request 和 wiki 中就是这样做的：[label](claude-cli://...) 只会渲染为 label，没有链接，网址也被移除。在这些平台上，请把深层链接放进一个代码块中，让读者能看到该网址并粘贴到浏览器地址栏中。

会话在我的主目录中打开，而不是在仓库中

repo 参数只能解析到 Claude Code 已经见过的克隆。在该克隆内运行一次 claude，让其路径被记录下来，或将该链接改为使用带绝对路径的 cwd。

该链接打开了错误的终端

在 macOS 上，在你偏好的终端中启动一次 claude，下一个深层链接就会使用它。在 Linux 上，将 $TERMINAL 环境变量设为你偏好的模拟器的命令名称。在 Windows 上，这个顺序是固定的：如果你想让链接在其中打开，而不是打开 PowerShell 或 cmd.exe 窗口，请安装 Windows Terminal。

了解更多

以下页面涵盖启动或扩展 Claude Code 会话的相关方式：

• 技能：把一份长的运行手册提示词存为仓库中的一个 /skill，这样深层链接的 q 参数只需要提及它的名字
• 非交互模式：从一个脚本运行 Claude，在不打开终端的情况下捕获输出