portal-ai-plugins: đưa Spotify Portal vào Claude Code, Codex — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về spotify/portal-ai-plugins — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: portal-ai-plugins: đưa Spotify Portal vào Claude Code, Codex, Cursor — cài và dùng →

Tóm tắt nhanh
portal-ai-plugins là bộ plugin chính thức của Spotify, giúp các trợ lý lập trình AI (Claude Code, Codex, Cursor, pi) làm việc với Spotify Portal thông qua Portal CLI. Bạn dùng nó để tìm kiếm catalog phần mềm, xem tóm tắt dịch vụ, chạy chẩn đoán và gọi các action của Portal bằng ngôn ngữ tự nhiên. Cài đặt chỉ vài lệnh, nhưng cần có quyền truy cập Spotify Portal của tổ chức bạn.
portal-ai-plugins là bộ plugin do Spotify phát hành, để các trợ lý lập trình AI như Claude Code, Codex, Cursor và pi làm việc được với Spotify Portal. Thay vì tự gõ lệnh Portal CLI, bạn nói với trợ lý điều bạn cần, và plugin sẽ gọi CLI thay bạn theo từng quy trình có sẵn.
Bộ plugin này dành cho người trong tổ chức đã dùng Spotify Portal: lập trình viên, kỹ sư vận hành, hoặc người quản lý kỹ thuật cần tra cứu dịch vụ nhanh. Nếu bạn chưa có Portal thì repo này chưa có nhiều giá trị với bạn. Người làm kinh doanh hoặc văn phòng có thể nhờ đồng nghiệp kỹ thuật cài, rồi tự hỏi bằng câu thường ngày.
Điểm đáng giá nhất là các thao tác có rào an toàn. Khi gọi một action của Portal, plugin có phần xem trợ giúp, chạy thử (dry-run) và hỏi xác nhận trước khi làm thật. Repo hiện có khoảng 3218 sao và 255 fork, dùng giấy phép Apache-2.0.
spotify/portal-ai-plugins
Plugin của Spotify đưa Spotify Portal vào Claude Code, Codex, Cursor và pi: tìm catalog phần mềm, tóm tắt dịch vụ, chạy action và Fleetshift.
I.portal-ai-plugins làm được gì
Mỗi chức năng là một "workflow" riêng. Bạn không cần nhớ lệnh, chỉ cần mô tả việc muốn làm.
- Thiết lập (setup): cấu hình đăng nhập Portal CLI cho môi trường trợ lý bạn đang dùng. Đây là bước đầu tiên và bạn chỉ làm một lần.
- Chẩn đoán (doctor): kiểm tra chỉ-đọc xem plugin, CLI, đăng nhập và các action đã sẵn sàng chưa. Khi có gì đó trục trặc, đây là chỗ nên thử đầu tiên vì nó không thay đổi gì.
- Tìm kiếm (search): tìm trong catalog phần mềm và tài liệu kỹ thuật bằng câu tự nhiên. Ví dụ bạn hỏi "dịch vụ nào lo phần thanh toán?" thay vì phải biết đúng tên dịch vụ.
- Tóm tắt dịch vụ (service): tạo bản tóm tắt ngắn về một dịch vụ, gồm các thông tin có sẵn như chủ sở hữu, tình trạng, sự cố và tài liệu. Rất tiện khi bạn vừa nhận bàn giao một dịch vụ lạ.
- Action của Portal (actions): tìm, xem chi tiết, xem trước và gọi các action. Có trợ giúp tích hợp, chạy thử và xác nhận để tránh bấm nhầm.
- Phản hồi (feedback): gửi góp ý về Portal CLI tới đội Portal.
- Fleetshift: gồm năm workflow. Bạn có thể tạo một "shift" từ mục tiêu (có bản xem trước dry-run), chạy shift và theo dõi với thời gian chờ có giới hạn, và dừng khi cần. Bạn cũng có thể xem tiến độ, đích và các PR (chỉ đọc), tìm nguyên nhân khi job lỗi (chỉ đọc), và mở PR cho các mục đã hoàn tất sau khi bạn xác nhận.
Ngoài ra, marketplace còn có thêm plugin shunt (hiện chỉ cho Claude Code). Nó chuyển các việc nặng I/O như đọc hàng loạt file hoặc sinh code mẫu sang các chế độ AiKA chạy mô hình worker rẻ hơn, qua registry action của Portal CLI. Chi tiết nằm trong plugins/shunt/README.md của repo.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về yêu cầu, nên mình chỉ ghi những gì chắc chắn:
- Một trong các công cụ: Claude Code, Codex, Cursor hoặc pi. Bạn cần có sẵn công cụ này.
- Lệnh
npx, vì các workflow gọi Portal CLI quanpx @spotify/portal-cli <command>.npxthường đi kèm Node.js. README không ghi phiên bản Node tối thiểu, nên bạn xem thêm trongpackage.jsoncủa repo nếu cần. - Quyền truy cập Spotify Portal của tổ chức bạn để đăng nhập ở bước setup. README không mô tả chi tiết cách cấp quyền, bạn hỏi quản trị viên Portal nếu chưa có.
- Cursor: cần dùng team marketplace của Cursor để đăng ký repo.
- README không nói về hệ điều hành hay phần cứng. Hướng dẫn dưới đây chỉ là lệnh terminal, không cần GPU.
Plugin dùng đăng nhập của bạn để đọc catalog và gọi action. Chỉ cài khi bạn được phép truy cập Portal, và luôn đọc phần xem trước (dry-run) trước khi xác nhận bất kỳ action nào thay đổi dữ liệu.
III.Cài đặt từng bước
Cách cài khác nhau theo từng công cụ. Bạn chọn đúng công cụ mình đang dùng.
- Chọn công cụClaude Code, Codex, Cursor hoặc pi
- Thêm marketplaceĐăng ký repo spotify/portal-ai-plugins
- Cài pluginCài plugin Spotify Portal (tên gói portal)
- Mở phiên mớiBắt đầu session hoặc task mới
- Chạy setupĐăng nhập Portal CLI qua workflow setup
A.Cài cho Claude Code
Mở terminal (PowerShell, Terminal hoặc cửa sổ lệnh bạn quen dùng), rồi chạy:
claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal # optional: token-saving AiKA delegationLệnh đầu thêm marketplace của Spotify. Lệnh thứ hai cài plugin chính tên portal. Lệnh thứ ba là tuỳ chọn, chỉ cần nếu bạn muốn dùng shunt để tiết kiệm token. Phần sau dấu # chỉ là ghi chú, bạn không cần gõ.
Sau đó mở một session mới của Claude Code và chạy:
/portal:setupChỗ người mới hay vấp: nếu không mở session mới, plugin có thể chưa được nạp.
B.Cài cho Codex
codex plugin marketplace add spotify/portal-ai-plugins
codexTrong Codex, mở /plugins, cài Spotify Portal, bắt đầu một task mới rồi gõ:
Set up Spotify Portal for me.C.Cài cho Cursor
README mô tả bằng giao diện, không có lệnh. Bạn đăng ký repo [spotify/portal-ai-plugins] vào team marketplace của Cursor, rồi vào Cursor Settings → Plugins để cài Spotify Portal. Thường bước đăng ký marketplace cần quyền quản trị của team, nên hãy nhờ người phụ trách nếu bạn không thấy tuỳ chọn.
D.Cài cho pi
pi install git:github.com/spotify/portal-ai-pluginsMở session mới và chạy:
/skill:setupE.Đăng nhập Portal CLI
Bước setup ở trên chính là phần đăng nhập. Theo README, setup kiểm tra các lệnh auth, actions, owner, search và service của Portal CLI trước khi tiếp tục. Hãy làm theo các hướng dẫn hiện ra trong phiên. README không ghi chi tiết từng màn hình đăng nhập.
Các workflow gọi CLI qua lệnh sau. Bạn không cần tự chạy, nhưng nên biết nó tồn tại:
npx @spotify/portal-cli <command>IV.Kiểm tra đã chạy được chưa
Cách an toàn nhất là nhờ workflow doctor. Nó chạy chẩn đoán chỉ-đọc để kiểm tra plugin, CLI, đăng nhập và các action. Bạn có thể nói với trợ lý một câu như:
Chạy doctor của Spotify Portal giúp mình.Nếu mọi thứ báo sẵn sàng thì bạn đã cài xong. Nếu có mục báo lỗi, bạn làm lại bước setup rồi chạy lại doctor. README không mô tả chính xác nội dung màn hình kết quả, nên bạn cứ đọc thông báo từng mục mà trợ lý hiển thị.
Một cách thử nhanh nữa là hỏi thử một việc tìm kiếm nhỏ (xem tình huống đầu tiên bên dưới). Nếu trợ lý trả lời bằng dữ liệu thật từ catalog của tổ chức bạn thì đường dẫn từ plugin đến Portal đã thông.
V.Dùng vào việc thật
Các tình huống dưới đây dựa trên các workflow trong README. Câu lệnh mẫu chỉ là cách diễn đạt gợi ý, bạn đổi theo ngữ cảnh của mình.
A.Tìm đúng dịch vụ trong catalog
Bạn là nhân viên mới trong đội kỹ thuật và chưa biết dịch vụ nào là của ai. Thay vì hỏi từng người, bạn nhờ workflow search:
Tìm trong catalog Portal các dịch vụ liên quan đến thanh toán, kèm tài liệu kỹ thuật nếu có.Kết quả là danh sách dịch vụ và tài liệu khớp với câu hỏi. Từ đó bạn biết nên đọc gì trước và hỏi ai.
B.Đọc nhanh một dịch vụ vừa được bàn giao
Sáng nay bạn nhận quản lý một dịch vụ cũ. Bạn nhờ workflow service:
Tóm tắt dịch vụ <tên dịch vụ> trong Portal: ai sở hữu, tình trạng hiện tại, sự cố gần đây và tài liệu.Bạn nhận một bản tóm tắt ngắn gọn với các thông tin Portal có sẵn như chủ sở hữu, tình trạng, sự cố và tài liệu. Thông tin nào Portal không có thì bản tóm tắt cũng sẽ không có, nên đừng coi đó là toàn bộ sự thật.
Cái hay nhất của plugin này là bạn được xem trước mọi thứ trước khi để AI làm thật.
Ông T
C.Gọi một action có kiểm soát
Bạn cần chạy một action của Portal nhưng chưa nhớ tham số. Hãy nhờ workflow actions:
Liệt kê các action Portal mà mình có thể gọi, giải thích action <tên action>, rồi chạy thử (dry-run) trước khi làm thật.Trợ lý sẽ tìm action, giải thích cách dùng, cho bạn xem bản xem trước, và chỉ làm thật khi bạn xác nhận. Với người mới, đây là cách học action nhanh mà ít rủi ro nhất.
D.Chạy một đợt thay đổi hàng loạt bằng Fleetshift
Đội bạn cần cập nhật cùng một thay đổi trên nhiều kho code. Bạn mô tả mục tiêu cho workflow fleetshift-create-shift, xem bản dry-run, rồi để fleetshift-run-shift chạy và theo dõi với thời gian chờ có giới hạn:
Tạo một shift Fleetshift với mục tiêu: <mô tả thay đổi>. Cho mình xem bản xem trước trước khi tạo.Sau đó bạn dùng fleetshift-check-shift để xem tiến độ và các PR, và fleetshift-troubleshoot-shift nếu job nào lỗi. Khi các mục đã hoàn tất, fleetshift-create-prs mở PR sau khi bạn xác nhận. Bạn cũng có thể yêu cầu dừng shift bất cứ lúc nào.
VI.Lỗi hay gặp và cách xử lý
A.Gõ lệnh slash nhưng không thấy gì
Thường là do plugin chưa được nạp. Hãy đóng session, mở session mới rồi chạy lại /portal:setup (Claude Code) hoặc /skill:setup (pi). Với Codex, kiểm tra xem bạn đã cài Spotify Portal trong /plugins chưa.
B.Không thấy plugin trong Cursor
Bước đăng ký marketplace ở Cursor làm ở mức team. Nếu bạn không thấy Spotify Portal trong Cursor Settings → Plugins, hãy kiểm tra repo đã được đăng ký vào team marketplace chưa, và hỏi quản trị viên team.
C.npx không chạy hoặc báo không tìm thấy lệnh
Workflow gọi Portal CLI qua npx, nên máy bạn cần có công cụ này. npx thường đi kèm Node.js. Cài Node.js từ trang chính thức rồi mở terminal mới. Nếu vẫn lỗi, xem yêu cầu phiên bản trong package.json của repo.
D.Đăng nhập thất bại hoặc hết hạn
Chạy lại workflow setup, sau đó chạy doctor để xác nhận. Nếu vẫn không được, nhiều khả năng tài khoản của bạn chưa có quyền vào Portal, và bạn cần hỏi người quản trị. Đừng chia sẻ thông tin đăng nhập qua chat hay email.
E.Action không chạy như mong đợi
Đừng bỏ qua bước xem trước. Dùng dry-run để xem chính xác điều sẽ xảy ra, đọc kỹ rồi mới xác nhận. Nếu kết quả khác với dự đoán của bạn, dừng lại và nhờ người phụ trách action đó kiểm tra. Gặp lỗi lạ, bạn có thể dùng workflow feedback để báo cho đội Portal.
VII.Có nên dùng không
Điểm mạnh:
- Do chính Spotify phát hành, giấy phép Apache-2.0, repo còn được cập nhật trong vài tháng gần đây.
- Hỗ trợ bốn công cụ phổ biến (Claude Code, Codex, Cursor, pi), nên đổi công cụ không phải học lại từ đầu.
- Có rào an toàn rõ ràng: chẩn đoán chỉ-đọc, dry-run, xác nhận trước khi làm thật.
- Quy trình được đóng gói thành workflow riêng, nên bạn nói điều cần làm thay vì nhớ lệnh.
Giới hạn:
- Chỉ có ích khi tổ chức bạn dùng Spotify Portal. Không có Portal thì plugin không giúp được gì.
- Phụ thuộc vào Portal CLI. README cho biết các workflow đều gọi qua
npx @spotify/portal-cli. - Plugin shunt hiện chỉ dùng cho Claude Code.
- README không nói rõ về hệ điều hành, phiên bản Node hay quy trình cấp quyền, nên bạn cần hỏi người quản trị Portal ở chỗ này.
- Chất lượng tóm tắt và tìm kiếm tuỳ vào dữ liệu có trong catalog của bạn.
Khi nào chọn cách khác: nếu bạn chỉ cần một trợ lý lập trình thông thường mà không có Portal, plugin này không cần thiết. Nếu bạn muốn tự động hoá các việc ngoài Portal, bạn cần plugin hoặc công cụ khác. Còn nếu đội bạn đã dùng Portal và muốn hỏi trợ lý thay vì mở giao diện web, đây là lựa chọn tự nhiên và khá an toàn để thử.
Câu hỏi thường gặp
portal-ai-plugins là gì?
Đây là bộ plugin của Spotify để đưa Spotify Portal vào Claude Code, Codex, Cursor và pi. Nó cung cấp các workflow như đăng nhập, tìm kiếm catalog, tóm tắt dịch vụ, gọi action và Fleetshift, đều chạy qua Portal CLI.
Có miễn phí không?
Repo dùng giấy phép Apache-2.0, nên mã nguồn mở. Tư liệu không nói gì về chi phí của Spotify Portal hay của công cụ AI mà bạn dùng cùng, nên mình chưa có thông tin về phần đó.
Cần GPU hoặc máy mạnh không?
README không nêu yêu cầu phần cứng. Cài đặt chỉ gồm các lệnh terminal và gọi Portal CLI qua npx, nên không có dấu hiệu cần GPU.
Chạy trên Windows được không?
README không nói rõ về hệ điều hành. Các lệnh cài đặt đều là lệnh terminal thông thường của Claude Code, Codex và pi. Bạn nên thử và dùng workflow doctor để kiểm tra.
Tôi cần tài khoản gì?
Bạn cần quyền truy cập Spotify Portal của tổ chức, vì bước setup sẽ cấu hình đăng nhập cho Portal CLI. README không mô tả chi tiết cách cấp quyền, nên hãy hỏi quản trị viên Portal nếu bạn chưa có.
Plugin có tự làm thay đổi dữ liệu không?
Theo README, các action đi kèm trợ giúp tích hợp, dry-run và bước xác nhận. Việc mở PR từ Fleetshift cũng chỉ diễn ra sau khi bạn xác nhận. Các workflow doctor, check và troubleshoot là chỉ-đọc.
shunt là gì, có bắt buộc cài không?
shunt là plugin tuỳ chọn, hiện chỉ cho Claude Code. Nó chuyển các việc nặng I/O như đọc hàng loạt file hoặc sinh code mẫu sang mô hình worker rẻ hơn để tiết kiệm token. Bạn không cần cài nó để dùng plugin chính.


