Kết nối Zed với Claude qua cổng API

Zed nhanh và trợ lý của nó thực sự hữu ích, nhưng cách thiết lập điểm cuối Claude tùy chỉnh không nằm ở nơi phần lớn người dùng tìm đến đầu tiên. Nhà cung cấp Anthropic tích hợp sẵn không cho phép ghi đè URL cơ sở, vì vậy cách kết nối thuận tiện với cổng kết nối là thông qua khối openai_compatible của Zed.

Vì sao không dùng nhà cung cấp Anthropic

Zed có sẵn nhà cung cấp Anthropic tích hợp, và phản xạ tự nhiên là trỏ nó đến cổng kết nối. Vấn đề là nhà cung cấp này không có cài đặt api_url, nên không có trường được hỗ trợ để chuyển hướng nó khỏi máy chủ Anthropic mặc định.

Chính hạn chế này khiến nhiều người gặp bế tắc. Thay vì cố khắc phục nó, bạn định tuyến Claude qua cơ chế openai_compatible tổng quát, vốn cho phép thiết lập URL cơ sở và được xây dựng riêng cho các điểm cuối bên thứ ba.

Bạn có thể hình dung nhà cung cấp tích hợp sẵn được gắn cố định với một đích đến, còn nhà cung cấp openai_compatible có thể cấu hình được. Với cổng kết nối đa mô hình, đường kết nối có thể cấu hình cũng chính là lựa chọn phù hợp, vì cùng một khối có thể cung cấp quyền truy cập Claude và mọi mô hình khác mà cổng kết nối phục vụ thông qua một api_url duy nhất. Nhờ đó, toàn bộ cấu hình mô hình của trình soạn thảo được tập trung ở một nơi, thay vì chia giữa hai cơ chế nhà cung cấp có quy tắc khác nhau. Quyết định này định hình phần còn lại của quá trình thiết lập, vì vậy bạn nên hiểu rõ trước khi chỉnh sửa bất cứ thứ gì. Khi đã xác định khối openai_compatible là cách kết nối được hỗ trợ, phần còn lại chỉ là điền các trường.

Thêm khối openai_compatible

Trong settings.json, bên dưới language_models.openai_compatible, hãy thêm một nhà cung cấp có tên. Đặt api_url của nhà cung cấp thành địa chỉ cổng kết nối với /v1 ở cuối; Zed sẽ gọi /chat/completions bên dưới đường dẫn đó, nên giao diện tương thích OpenAI của cổng kết nối sẽ xử lý yêu cầu.

Bạn có thể tùy ý chọn tên, và tên đó sẽ trở thành nhãn trong menu mô hình của Zed. Một khối có thể phục vụ nhiều mô hình Claude, mỗi mô hình được khai báo ở bước tiếp theo.

Hậu tố /v1 đóng vai trò thiết yếu ở đây: Zed tạo đường dẫn chat-completions ngay dưới giá trị bạn cung cấp cho api_url, nên thiếu /v1 sẽ gửi yêu cầu đến sai vị trí, còn dấu gạch chéo ở cuối có thể khiến đường dẫn bị lặp. Hãy đặt chính xác thành địa chỉ máy chủ cộng với /v1 để định tuyến đúng. Tải lại cài đặt sau khi chỉnh sửa sẽ xác nhận rằng Zed đã phân tích khối mà không báo lỗi. Nếu nhà cung cấp không xuất hiện, điều đầu tiên cần kiểm tra là lỗi cú pháp JSON trong khối.

Khai báo available_models

Zed không tự động phát hiện mô hình trên điểm cuối tùy chỉnh, vì vậy hãy liệt kê chúng thủ công trong available_models. Mỗi mục cần có name khớp với mã định danh trên cổng kết nối, display_name để hiển thị trong menu và giá trị max_tokens phù hợp với mô hình.

Dùng claude-sonnet-4-5 cho hỗ trợ thường ngày và thêm claude-opus-4-8 làm mục thứ hai cho các tác vụ khó nhất. Vì bạn liệt kê chúng một cách tường minh, menu sẽ chỉ hiển thị đúng tập hợp bạn muốn.

Trường name phải khớp từng ký tự với mã định danh trên cổng kết nối, còn display_name chỉ dùng để hiển thị và có thể là bất kỳ tên nào bạn muốn trong menu. Nhập sai name là nguyên nhân phổ biến khiến mô hình xuất hiện nhưng báo lỗi khi sử dụng, vì vậy hãy sao chép mã định danh trực tiếp từ cổng kết nối thay vì gõ theo trí nhớ. Chỉ liệt kê các mô hình bạn thực sự dùng sẽ giúp menu ngắn gọn và dễ lựa chọn trong công việc hằng ngày. Sau này, thêm một mô hình chỉ cần chỉnh sửa một dòng, nên không cần khai báo mọi mô hình ngay từ đầu.

Nơi lưu khóa

Khóa API không được đặt trong settings.json. Zed lưu khóa trong kho khóa của hệ điều hành hoặc đọc từ biến môi trường được đặt tên theo nhà cung cấp, chẳng hạn AIPRIME_API_KEY, giúp thông tin bí mật không nằm trong cấu hình được đồng bộ hóa.

Sau khi lưu, hãy mở trợ lý, chọn nhà cung cấp của bạn trong menu và nhập khóa khi được nhắc. Từ đó, Zed dùng khóa trong kho khóa để xác thực, còn tệp cài đặt của bạn không chứa thông tin xác thực.

Việc tách biệt này thực sự hữu ích nếu bạn đồng bộ cài đặt Zed giữa các máy hoặc đưa chúng vào kho mã dotfiles: cấu hình có thể được chuyển tự do vì không chứa thông tin bí mật, và mỗi máy cung cấp khóa riêng qua kho khóa hoặc biến môi trường. Cách này gọn gàng hơn các công cụ nhúng khóa vào tệp cấu hình. Đây cũng là lý do bạn có thể chia sẻ cấu hình Zed với đồng nghiệp một cách an toàn — họ dùng khóa riêng và khóa của bạn không được gửi đi. Điều tương tự cũng áp dụng khi đưa cài đặt vào kho mã dotfiles.

Kết nối theo cơ chế gốc qua ACP

Nếu bạn muốn hành vi Anthropic gốc thay vì giao diện tương thích OpenAI, Zed hỗ trợ Agent Client Protocol với Claude Code. Bạn chạy Claude Code làm tác tử, và Zed giao tiếp với nó qua ACP.

Trong cách thiết lập đó, Claude Code có ANTHROPIC_BASE_URL riêng trỏ đến cổng kết nối, nên Zed không cần api_url Anthropic riêng. Đây là cách thuận tiện nhất để có hành vi Messages gốc thực sự ngay trong trình soạn thảo.

Đổi lại, ACP cung cấp toàn bộ vòng lặp tác tử của Claude Code thay vì trợ lý tích hợp gọn nhẹ hơn của Zed, nên có nhiều khả năng hơn nhưng trải nghiệm cũng nặng nề hơn. Chọn cách kết nối openai_compatible để được hỗ trợ nhanh ngay trong mã, và chọn ACP khi bạn muốn một tác tử đầy đủ thực hiện các chỉnh sửa nhiều bước từ bên trong trình soạn thảo. Phần lớn người dùng bắt đầu với cách kết nối nhẹ hơn và chỉ chuyển sang ACP khi muốn có tác tử đầy đủ trong trình soạn thảo. Bạn có thể duy trì cả hai và chọn cách phù hợp với từng tác vụ.

// Zed settings.json
{
  "language_models": {
    "openai_compatible": {
      "aiprime": {
        "api_url": "https://aiprimetech.io/v1",
        "available_models": [
          { "name": "claude-sonnet-4-5",
            "display_name": "Claude Sonnet",
            "max_tokens": 200000 }
        ]
      }
    }
  }
}
// Key goes in the keychain / AIPRIME_API_KEY env var, NOT this file.

Câu hỏi thường gặp

AI Prime Tech là một cổng API độc lập. AI Prime Tech không liên kết với, không được Anthropic chứng thực và không phải là đại lý bán lại của Anthropic. Claude và các tên mô hình liên quan là nhãn hiệu của chủ sở hữu tương ứng.