Deep Links — 从链接启动会话

是什么

Deep Links 是 claude-cli:// 自定义 URL Scheme，点击后在本地打开新终端窗口并启动 Claude Code 会话，可携带工作目录和预填充的 Prompt。Prompt 填入输入框但不自动发送，用户确认后才执行。需要 v2.1.91+。

核心机制

URL 格式：

claude-cli://open?repo=owner/name&q=URL-encoded-prompt

参数：

• q：预填充的 Prompt 文本（URL 编码，%0A 换行，最长 5000 字符）
• cwd：绝对路径工作目录（网络路径和 UNC 路径被拒绝）
• repo：GitHub owner/name slug，解析到本地最近使用的 clone

cwd vs repo：

• cwd：所有人都在相同绝对路径时使用（如标准化 devcontainer）
• repo：链接共享给多人时使用，每人解析到自己的本地 clone

注册机制：首次启动交互式会话时自动注册，无需手动安装：

• macOS：~/Applications/Claude Code URL Handler.app
• Linux：~/.local/share/applications/claude-code-url-handler.desktop
• Windows：HKEY_CURRENT_USER\Software\Classes\claude-cli

GitHub Markdown 限制：GitHub 过滤非 http/https URL Scheme，claude-cli:// 链接在 README/Issue/PR 中显示为纯文本。解决方案：放在代码块中让用户复制粘贴。

关键细节

• 从 Shell 打开（macOS）：open "claude-cli://open?repo=..."
• 从 Shell 打开（Linux）：xdg-open "claude-cli://open?..."
• 禁用注册：disableDeepLinkRegistration: "disable"
• VS Code 版本：vscode://anthropic.claude-code/open（打开编辑器标签页）
• repo 只解析到曾经运行过 claude 的 clone

关联

• skills — 将长 Prompt 存为 Skill，Deep Link 只需引用 Skill 名
• headless — 非交互式运行（不打开终端窗口）

实践要点

• 典型用途：运维手册中的诊断链接、监控告警中的调查链接、README 中的入门链接
• 长 Prompt（>1000 字符）会有提示要求用户滚动查看完整内容
• repo 参数解析到最近使用的 clone，多个 clone 时选最近的
• 链接本身不执行任何操作，只填充 Prompt，安全性由用户确认保证
• 企业可通过 managed settings 强制禁用 Deep Link 注册