Deep link là một URL claude-cli:// mở Claude Code trong một cửa sổ terminal mới. URL này có thể mang theo thư mục làm việc và một prompt điền sẵn - nhúng vào runbook, cảnh báo giám sát, hay dashboard để một cú click là mở đúng Claude Code trong đúng repo với đúng prompt.
Đây là cách chia sẻ một điểm bắt đầu one-click cho một tác vụ: bất kỳ ai cài Claude Code mà click vào link sẽ thấy một phiên mở ra với prompt đã gõ sẵn. Prompt được điền sẵn nhưng không tự gửi cho đến khi bạn nhấn Enter.
Vì deep link chỉ là một URL, bạn có thể đặt nó ở bất cứ đâu có thể chèn link:
- Một bước trong runbook xử lý sự cố, mở repo của service bị ảnh hưởng kèm prompt chẩn đoán
- Một cảnh báo giám sát hay dashboard link tới prompt điều tra cho một metric cụ thể
- README hay wiki mở project kèm prompt onboarding
- Thông báo CI fail điền sẵn tên job bị lỗi
Cách hoạt động
Phần tiêu đề “Cách hoạt động”Tiền tố claude-cli:// là một custom URL scheme mà Claude Code đăng ký với hệ điều hành, tương tự cách mailto: mở email client. Link có thể nằm trên trang web, wiki, tin nhắn Slack, hay bất kỳ app nào render được link. Khi bạn click:
- Trình duyệt hoặc app chuyển URL cho hệ điều hành.
- Hệ điều hành nhận diện tiền tố
claude-cli://và khởi động Claude Code trên máy bạn. - Một cửa sổ terminal mới mở ra với Claude Code chạy trong thư mục link chỉ định, prompt của link đã có sẵn trong ô input.
- Bạn đọc prompt, có thể sửa, rồi nhấn Enter để gửi.
Link có thể host ở đâu cũng được, nhưng phiên làm việc luôn mở ra cục bộ trên máy bạn click. Xem Đăng ký và các nền tảng hỗ trợ để biết terminal emulator nào mở trên hệ điều hành nào.
Phiên làm việc mở ra hiển thị gì
Phần tiêu đề “Phiên làm việc mở ra hiển thị gì”Deep link không bao giờ tự thực thi gì cả. Link chỉ chọn thư mục và điền prompt box. Nếu bạn click một link từ trang không đáng tin, prompt vẫn trơ (inert): không có gì đến model cho tới khi bạn đọc nội dung điền sẵn và nhấn Enter.
Khi phiên mở ra, một dòng cảnh báo dưới ô input hiện Prompt from an external link và giữ nguyên cho đến khi bạn gửi hoặc xoá prompt. Với prompt dài hơn 1.000 ký tự, cảnh báo kèm số ký tự và nhắc bạn cuộn xem toàn bộ text trước khi nhấn Enter, vì prompt dài có thể đẩy chỉ dẫn ra ngoài màn hình. Permission rule, CLAUDE.md, và prompt xác nhận trust cho thư mục được chọn vẫn áp dụng như bình thường.
Tạo một link
Phần tiêu đề “Tạo một link”Mọi deep link bắt đầu bằng claude-cli://open, path duy nhất mà handler chấp nhận, theo sau là các query parameter tuỳ chọn. Dạng tối giản mở Claude Code trong thư mục home với prompt rỗng:
claude-cli://openĐể thử link mà không cần đặt lên trang nào, dán thẳng vào thanh địa chỉ trình duyệt hoặc mở từ shell.
Thêm parameter để điều khiển nơi phiên bắt đầu và nội dung prompt box:
| Parameter | Mô tả |
|---|---|
q | Text điền sẵn vào prompt box. URL-encode giá trị này. Dùng %0A cho xuống dòng trong prompt nhiều dòng. Tối đa 5.000 ký tự. |
cwd | Đường dẫn tuyệt đối làm thư mục làm việc. Network path và UNC path bị từ chối, cùng với path chứa ký tự ẩn hoặc ký tự điều khiển bidirectional. |
repo | Slug owner/name trên GitHub. Claude Code resolve về một bản clone cục bộ đã từng thấy trước đó và mở tại đó. Nếu không có clone khớp, phiên mở trong thư mục home. |
cwd và repo là hai cách khác nhau để đặt thư mục làm việc. Nếu truyền cả hai, cwd được ưu tiên và repo bị bỏ qua, kể cả khi path của cwd không tồn tại.
Ví dụ link dưới trỏ tới repo acme/payments kèm prompt chẩn đoán hai dòng. Thay acme/payments bằng slug owner/name của repo bạn khi tự tạo link:
claude-cli://open?repo=acme/payments&q=Investigate%20the%20failed%20deploy%20of%20payments-api.%0ACheck%20recent%20commits%20to%20main%20and%20the%20last%20successful%20build.Click vào đó sẽ mở một cửa sổ terminal mới, khởi động Claude Code trong bản clone cục bộ của acme/payments, và điền prompt box với text đã decode. Bạn có thể sửa prompt trước khi gửi. Nếu chưa có bản clone cục bộ của repo, phiên mở trong thư mục home thay vào đó.
Chọn giữa cwd và repo
Phần tiêu đề “Chọn giữa cwd và repo”Dùng cwd khi mọi người click link đều có project ở cùng một đường dẫn tuyệt đối, ví dụ một devcontainer hay VM image chuẩn hoá.
Dùng repo khi link được chia sẻ và mỗi người clone vào vị trí khác nhau. Claude Code resolve slug thành đường dẫn cục bộ như sau:
- Mỗi lần bạn chạy
claudetrong một Git repository, Claude Code ghi lại thư mục đó ứng với slugowner/nametrên GitHub của repo. - Khi một deep link đến,
repomở đường dẫn khớp mà bạn dùng gần nhất. Claude Code theo dõi riêng nhiều clone và worktree, nên nó chọn cái bạn làm việc gần nhất. - Việc tra cứu chỉ tìm được các path mà bạn đã từng chạy Claude Code ít nhất một lần.
- Link không đổi branch đang checkout. Phiên mở ra ở đúng trạng thái hiện tại của thư mục đó.
Header chào mừng hiển thị path nào được chọn để bạn xác nhận đúng clone đã mở.
Ví dụ sử dụng
Phần tiêu đề “Ví dụ sử dụng”Nhúng link vào runbook
Phần tiêu đề “Nhúng link vào runbook”Deep link trong runbook cho người xử lý sự cố một cách one-click bắt đầu điều tra đúng repo với prompt chuẩn bị sẵn. Nền tảng render runbook phải cho phép custom URL scheme. Markdown của GitHub không cho phép claude-cli://, nên deep link trong README, issue, hay wiki của GitHub chỉ hiện label mà không click được. Xem ghi chú khắc phục để có cách né.
Prompt là một phần của URL và phải được URL-encode. Để tạo giá trị đã encode, chạy text prompt qua encodeURIComponent trong console trình duyệt hoặc bất kỳ URL encoder nào.
Ví dụ dưới thêm một điểm vào điều tra cho runbook xử lý sự cố của service web-gateway:
## Tỷ lệ 5xx cao trên web-gateway
1. Acknowledge cảnh báo trong PagerDuty.2. [Mở Claude Code trong repo gateway](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. Đăng phát hiện ban đầu vào #incident.Mở link từ shell
Phần tiêu đề “Mở link từ shell”Bạn cũng có thể mở deep link từ shell script, alias, hay automation thay vì click. Gọi lệnh mở URL của hệ điều hành với link làm tham số. Các lệnh này dựa vào handler mà Claude Code đăng ký khi bạn gửi prompt đầu tiên của một phiên interactive trên máy đó.
macOS, dùng lệnh open có sẵn:
open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Linux, hầu hết desktop environment cung cấp xdg-open:
xdg-open "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Windows PowerShell, Start-Process chuyển URL cho handler đã đăng ký:
Start-Process "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Trong cmd.exe, start coi tham số quote đầu tiên là tiêu đề cửa sổ, nên truyền một tiêu đề rỗng trước URL:
start "" "claude-cli://open?repo=acme/payments&q=review%20open%20PRs"Đăng ký và các nền tảng hỗ trợ
Phần tiêu đề “Đăng ký và các nền tảng hỗ trợ”Claude Code đăng ký handler claude-cli:// với hệ điều hành trên macOS, Linux, và Windows khi bạn gửi prompt đầu tiên của một phiên interactive. Chỉ khởi động claude rồi thoát mà không gửi prompt sẽ không đăng ký handler. Bạn không cần chạy lệnh cài riêng. Việc đăng ký chỉ ghi vào vị trí cấp user:
| Nền tảng | Vị trí handler |
|---|---|
| macOS | ~/Applications/Claude Code URL Handler.app |
| Linux | claude-code-url-handler.desktop trong $XDG_DATA_HOME/applications, mặc định ~/.local/share/applications |
| Windows | HKEY_CURRENT_USER\Software\Classes\claude-cli |
Handler khởi động Claude Code trong terminal emulator được phát hiện. Trên macOS, Claude Code nhớ terminal từ phiên interactive gần nhất và dùng lại, hỗ trợ iTerm2, Ghostty, kitty, Alacritty, WezTerm, và Terminal.app. Trên Linux nó tôn trọng biến môi trường $TERMINAL, sau đó x-terminal-emulator, rồi tới danh sách emulator phổ biến. Trên Windows nó ưu tiên Windows Terminal, sau đó PowerShell, rồi cmd.exe.
Để ngăn hoàn toàn việc đăng ký, đặt disableDeepLinkRegistration thành "disable" trong settings.json. Để bắt buộc trên toàn tổ chức sao cho user không thể tự bật lại, đặt trong managed settings thay vào đó.
Mở tab VS Code thay vì terminal
Phần tiêu đề “Mở tab VS Code thay vì terminal”VS Code extension đăng ký handler riêng tại vscode://anthropic.claude-code/open, mở một tab editor Claude Code thay vì cửa sổ terminal.
Khắc phục sự cố
Phần tiêu đề “Khắc phục sự cố”Click vào link không có gì xảy ra
Phần tiêu đề “Click vào link không có gì xảy ra”Có thể handler chưa được đăng ký. Việc đăng ký xảy ra khi bạn gửi prompt đầu tiên của một phiên interactive, không phải khi phiên khởi động. Chạy một phiên claude interactive trên máy đó, gửi bất kỳ prompt nào, thoát, rồi thử link lại. Nếu bạn dùng Linux không có desktop environment, xdg-open có thể không có gì để chuyển tới.
xdg-open not found trên Linux
Phần tiêu đề “xdg-open not found trên Linux”Lệnh xdg-open nằm trong package xdg-utils, thứ mà các image server tối giản, container, và bản phân phối WSL thường không cài sẵn. Cài xdg-utils bằng package manager của bản phân phối, ví dụ sudo apt install xdg-utils, rồi chạy lại lệnh.
Link hiện dạng text thường thay vì click được
Phần tiêu đề “Link hiện dạng text thường thay vì click được”Một số Markdown renderer chỉ cho phép link http/https và loại bỏ scheme khác. GitHub làm vậy trong README, issue, pull request, và wiki: [label](claude-cli://...) chỉ render ra label, không có link, URL bị xoá. Trên các nền tảng này, đặt deep link trong code block để người đọc thấy URL và tự dán vào thanh địa chỉ trình duyệt.
Phiên mở trong thư mục home thay vì repo
Phần tiêu đề “Phiên mở trong thư mục home thay vì repo”Parameter repo chỉ resolve về các clone Claude Code đã từng thấy. Chạy claude trong clone đó một lần để Claude Code ghi lại path, hoặc chuyển link sang dùng cwd với đường dẫn tuyệt đối.
Link mở sai terminal
Phần tiêu đề “Link mở sai terminal”Trên macOS, khởi động claude trong terminal ưa thích một lần rồi deep link tiếp theo sẽ dùng nó. Trên Linux, đặt biến môi trường $TERMINAL thành tên lệnh của emulator ưa thích. Trên Windows, thứ tự cố định: cài Windows Terminal nếu muốn link mở ở đó thay vì cửa sổ PowerShell hay cmd.exe.
lượt xem
