{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 从链接启动会话

> 从 URL 打开 Claude Code 终端会话。将 `claude-cli://` 链接嵌入手册、警报和仪表板中，一次点击即可在正确的仓库中打开 Claude Code 并预填正确的提示。

深度链接是一个 `claude-cli://` URL，它在新终端窗口中打开 Claude Code。该 URL 可以携带工作目录和预填提示。

这让你可以分享一个一键启动任务的起点：任何安装了 Claude Code 的人点击链接后，会看到一个已预填提示的会话。提示已填充但不会发送，直到你按 Enter。

因为深度链接是一个 URL，你可以将它放在任何可以放置链接的地方：

* 事件手册中的步骤，打开受影响服务的仓库并附带诊断提示
* 监控警报或仪表板，链接到特定指标的调查提示
* README 或 wiki 页面，打开项目并附带入门提示
* CI 失败通知，预填失败作业的名称

本页面介绍如何[构建链接](#构建链接)、[将其嵌入手册或从 shell 触发](#示例)，以及在每个平台上[管理或禁用处理程序注册](#注册和支持的平台)。

<Note>
  深度链接需要 Claude Code v2.1.91 或更高版本。
</Note>

## 工作原理

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

1. 浏览器或应用将 URL 交给你的操作系统。
2. 操作系统识别 `claude-cli://` 前缀并在你的机器上启动 Claude Code。
3. 一个新的终端窗口打开，Claude Code 在链接指定的目录中运行，链接的提示文本已在输入框中。
4. 你阅读提示，根据需要编辑，然后按 Enter 发送。

链接本身可以托管在任何地方，但会话总是在你点击的计算机上本地打开。有关每个操作系统上打开哪个终端模拟器，请参阅[注册和支持的平台](#注册和支持的平台)。

<Note>
  显示链接的平台必须允许自定义 URL 方案。GitHub 渲染的 Markdown 允许 `http` 和 `https`，但在 README、issue、拉取请求和 wiki 中会剥离 `claude-cli://` 等方案。仅显示链接文本，没有链接且 URL 被隐藏。有关解决方法，请参阅[故障排除](#链接显示为纯文本而非可点击)。
</Note>

### 启动的会话显示什么

深度链接本身不会执行任何操作。链接只选择一个目录并填充提示框。如果你从不信任的页面点击链接，提示仍然是惰性的：在你阅读填充内容并按 Enter 之前，不会有任何内容发送到模型。

当会话打开时，输入框上方的横幅会显示是外部链接启动了它以及它选择了哪个目录。对于超过 1,000 个字符的提示，横幅会告诉你在按 Enter 之前滚动并审查完整文本，因为长提示可能会将指令推到屏幕之外。所选目录的权限规则、`CLAUDE.md` 和信任提示与任何其他会话的适用方式相同。

## 构建链接

每个深度链接都以 `claude-cli://open` 开头，这是处理程序接受的唯一路径，后跟可选的查询参数。最小形式在你的主目录中打开 Claude Code 并带有空提示：

```text theme={null}
claude-cli://open
```

添加参数来控制会话启动位置和提示框内容：

| 参数     | 描述                                                                                                                                                                                                                                    |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`      | 预填在提示框中的文本。对值进行 [URL 编码](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)。在多行提示中使用 `%0A` 表示换行。最多 5,000 个字符。                                    |
| `cwd`    | 用作工作目录的绝对路径。网络和 UNC 路径会被拒绝。                                                                                                                                                                                       |
| `repo`   | GitHub `owner/name` 标识符。Claude Code 将其解析为之前见过的本地克隆并在那里启动。如果你没有匹配的克隆，会话将在你的主目录中打开。                                                                                                     |

`cwd` 和 `repo` 是[设置工作目录的两种方式](#在-cwd-和-repo-之间选择)。如果同时传递两者，`cwd` 优先，`repo` 被忽略，即使 `cwd` 路径不存在。

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

```text theme={null}
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，并将解码后的文本填充到提示框中：

```text theme={null}
Investigate the failed deploy of payments-api.
Check recent commits to main and the last successful build.
```

你可以在按 Enter 发送之前编辑提示。如果你没有该仓库的本地克隆，会话将在你的主目录中打开。有关当你有多个克隆或工作树时如何选择本地路径，请参阅[在 `cwd` 和 `repo` 之间选择](#在-cwd-和-repo-之间选择)。

### 在 `cwd` 和 `repo` 之间选择

当点击链接的每个人都将项目放在相同的绝对路径时使用 `cwd`，例如标准化的 devcontainer 或 VM 镜像。

当链接被共享且每个人克隆到不同位置时使用 `repo`。Claude Code 按以下方式将标识符解析为本地路径：

* 每次你在 Git 仓库中运行 `claude` 时，该目录的文件系统路径会与仓库的 GitHub `owner/name` 标识符一起记录。
* 当深度链接到达时，`repo` 会打开你最近使用过的匹配路径。多个克隆和工作树被单独跟踪，因此它会选择你最后工作的那个。
* 查找只会找到你已至少运行过一次 Claude Code 的路径。
* 该链接不会更改检出的分支。会话在该目录当前状态下打开。

启动的会话会显示它选择了哪个路径以及该克隆最后一次从远程获取的时间，这样你就能知道你查看的是否是过时的代码。

## 示例

以下部分展示两种使用深度链接的常见方式：作为文档中的 Markdown 链接，以及作为脚本或 shell 别名中的命令。

### 在手册中嵌入链接

手册中的深度链接为正在分类问题的人提供一键方式，使用准备好的提示在正确的仓库中开始调查。渲染手册的平台必须允许自定义 URL 方案。GitHub 渲染的 Markdown 不允许 `claude-cli://`，因此 GitHub README、issue 或 wiki 中的深度链接仅显示其标签，没有可点击的链接。有关解决方法，请参阅[故障排除说明](#链接显示为纯文本而非可点击)。

提示是 URL 的一部分，必须进行 URL 编码。要生成编码值，请在浏览器控制台或任何 URL 编码器中将提示文本通过 `encodeURIComponent` 传递。

以下示例为名为 `web-gateway` 的服务的事件手册添加调查入口点：

```markdown theme={null}
## 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 脚本、别名或自动化中打开深度链接，而不是通过点击。将链接作为参数调用操作系统的 URL 打开命令。

<Tabs>
  <Tab title="macOS">
    内置的 `open` 命令将 URL 传递给已注册的 `claude-cli://` 处理程序：

    ```bash theme={null}
    open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
    ```
  </Tab>

  <Tab title="Linux">
    大多数桌面环境提供 `xdg-open`，它将 URL 传递给已注册的处理程序：

    ```bash theme={null}
    xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
    ```
  </Tab>

  <Tab title="Windows">
    在 PowerShell 中，`Start-Process` 将 URL 传递给已注册的处理程序：

    ```powershell theme={null}
    Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
    ```

    在 `cmd.exe` 中，`start` 将其第一个带引号的参数视为窗口标题，因此在 URL 之前传递一个空标题：

    ```cmd theme={null}
    start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"
    ```
  </Tab>
</Tabs>

## 注册和支持的平台

Claude Code 在 macOS、Linux 和 Windows 上首次启动交互式会话时，会向操作系统注册 `claude-cli://` 处理程序。你无需运行单独的安装命令。注册仅写入用户级位置：

| 平台    | 处理程序位置                                                                                                            |
| ------- | ----------------------------------------------------------------------------------------------------------------------- |
| macOS   | `~/Applications/Claude Code URL Handler.app`                                                                            |
| Linux   | `$XDG_DATA_HOME/applications` 下的 `claude-code-url-handler.desktop`，默认为 `~/.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`](/en/settings) 设置为 `"disable"`。要跨组织强制执行此设置，使用户无法重新启用，请在[托管设置](/en/server-managed-settings)中设置。

## 打开 VS Code 标签页而非终端

VS Code 扩展在 `vscode://anthropic.claude-code/open` 注册了自己的处理程序，它会打开 Claude Code 编辑器标签页而不是终端窗口。有关该 URL 的参数，请参阅[从其他工具启动 VS Code 标签页](/en/vs-code#launch-a-vs-code-tab-from-other-tools)。

## 故障排除

### 点击链接没有任何反应

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

### 链接显示为纯文本而非可点击

某些 Markdown 渲染器仅允许 `http` 和 `https` 链接，并剥离其他 URL 方案。GitHub 在 README、issue、拉取请求和 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 会话的相关方式：

* [技能](/en/skills)：将长手册提示存储为仓库中的 `/skill`，这样深度链接的 `q` 参数只需命名它
* [非交互模式](/en/headless)：从脚本运行 Claude 并捕获输出，无需打开终端