게이트웨이를 통해 Zed를 Claude에 연결하기

Zed는 빠르고 어시스턴트도 유용하지만, 사용자 지정 Claude 엔드포인트를 설정하는 위치는 대부분의 사람이 처음 찾아보는 곳과 다릅니다. 기본 제공 Anthropic 제공자는 기본 URL 재정의 기능을 제공하지 않으므로, 게이트웨이에 연결하는 간단한 방법은 Zed의 openai_compatible 블록을 사용하는 것입니다.

Anthropic 제공자를 사용하지 않는 이유

Zed에는 Anthropic 제공자가 기본으로 포함되어 있어, 자연스럽게 이를 게이트웨이에 연결하려고 할 수 있습니다. 하지만 이 제공자에는 api_url 설정이 없으므로, 기본 Anthropic 호스트 대신 다른 곳으로 연결할 수 있는 지원 필드가 없습니다.

많은 사람이 막히는 이유가 바로 이 제한입니다. 이를 억지로 해결하려 하기보다, 기본 URL 설정을 제공하고 외부 엔드포인트를 위해 설계된 범용 openai_compatible 방식을 통해 Claude에 연결하면 됩니다.

기본 제공 제공자는 하나의 목적지에 고정되어 있고, openai_compatible 제공자는 설정을 변경할 수 있다고 생각하면 이해하기 쉽습니다. 멀티 모델 게이트웨이에는 설정 가능한 방식이 적합합니다. 같은 블록에서 하나의 api_url을 통해 Claude와 게이트웨이가 제공하는 다른 모든 모델에 연결할 수 있기 때문입니다. 이렇게 하면 서로 다른 규칙을 가진 두 제공자 방식으로 나누지 않고 편집기의 모든 모델 설정을 한곳에서 관리할 수 있습니다. 이 선택이 이후 설정 전체를 결정하므로, 편집하기 전에 명확히 이해하는 것이 좋습니다. openai_compatible 블록이 지원되는 연결 방식이라는 점을 이해하면, 나머지는 필드를 채우기만 하면 됩니다.

openai_compatible 블록 추가

settings.json의 language_models.openai_compatible 아래에 이름이 있는 제공자를 추가하세요. api_url을 끝에 /v1이 붙은 게이트웨이 주소로 설정하세요. Zed는 그 아래의 /chat/completions를 호출하므로, 게이트웨이의 OpenAI 호환 인터페이스가 응답합니다.

이름은 자유롭게 정할 수 있으며, Zed의 모델 메뉴에서 표시 이름으로 사용됩니다. 하나의 블록으로 여러 Claude 모델을 제공할 수 있고, 각 모델은 다음 단계에서 선언합니다.

여기서 /v1 접미사는 필수입니다. Zed는 api_url로 지정한 주소 바로 아래에 채팅 완성 경로를 구성하므로, /v1이 없으면 요청이 잘못된 위치로 전송되고 끝에 슬래시가 있으면 경로가 중복될 수 있습니다. 호스트에 /v1만 정확히 붙여 설정하면 올바르게 라우팅됩니다. 편집 후 설정을 간단히 다시 로드하면 Zed가 오류 없이 블록을 해석했는지 확인할 수 있습니다. 제공자가 나타나지 않으면 먼저 블록의 JSON 구문 오류를 확인하세요.

available_models 선언

Zed는 사용자 지정 엔드포인트의 모델을 자동으로 검색하지 않으므로, available_models에 직접 나열하세요. 각 항목에는 게이트웨이 ID와 일치하는 name, 메뉴에 표시할 display_name, 모델에 맞게 지정한 max_tokens 값이 필요합니다.

일상적인 지원에는 claude-sonnet-4-5을 사용하고, 가장 어려운 작업을 위해 claude-opus-4-8을 추가 항목으로 등록하세요. 모델을 명시적으로 나열하므로 메뉴에는 원하는 모델만 정확히 표시됩니다.

name 필드는 게이트웨이의 ID와 문자 하나까지 일치해야 합니다. 반면 display_name은 표시 용도로만 사용되므로 메뉴에 원하는 이름을 넣을 수 있습니다. 모델이 표시되지만 사용 시 오류가 발생하는 가장 흔한 원인은 잘못된 name이므로, 기억에 의존해 입력하지 말고 게이트웨이에서 ID를 직접 복사하세요. 실제로 사용하는 모델만 나열하면 메뉴가 간결해지고 일상적인 작업에서 쉽게 선택할 수 있습니다. 나중에 모델을 추가하는 것은 한 줄만 수정하면 되므로, 처음부터 모든 모델을 선언할 필요는 없습니다.

키 저장 위치

API 키는 settings.json에 넣지 않습니다. Zed는 키를 운영체제 키체인에 저장하거나 AIPRIME_API_KEY처럼 제공자 이름을 따서 지정한 환경 변수에서 읽습니다. 따라서 동기화되는 설정에 비밀 정보가 포함되지 않습니다.

저장한 후 어시스턴트를 열고 메뉴에서 제공자를 선택한 다음, 메시지가 표시되면 키를 입력하세요. 이후 Zed는 키체인의 키로 인증하며, 설정 파일에는 인증 정보가 포함되지 않습니다.

이러한 분리는 여러 기기에서 Zed 설정을 동기화하거나 dotfiles 저장소에 커밋할 때 유용합니다. 설정에는 비밀 정보가 없으므로 자유롭게 옮길 수 있고, 각 기기는 키체인이나 환경 변수를 통해 자체 키를 제공합니다. 키를 설정 파일에 넣는 도구보다 깔끔한 방식입니다. 동료와 Zed 설정을 안전하게 공유할 수 있는 이유도 여기에 있습니다. 동료는 자신의 키를 사용하며, 사용자의 키는 전달되지 않습니다. 설정을 dotfiles 저장소에 커밋할 때도 마찬가지입니다.

ACP를 통한 네이티브 연결 방식

OpenAI 호환 인터페이스 대신 Anthropic의 네이티브 동작을 원한다면, Zed는 Claude Code를 통한 Agent Client Protocol을 지원합니다. Claude Code를 에이전트로 실행하면 Zed가 ACP를 통해 통신합니다.

이 구성에서는 Claude Code 자체의 ANTHROPIC_BASE_URL이 게이트웨이를 가리키므로, Zed에 별도의 Anthropic api_url이 필요하지 않습니다. 편집기 안에서 실제 네이티브 Messages 동작을 사용하는 가장 간단한 방법입니다.

고려할 점은 ACP가 Zed의 가벼운 기본 어시스턴트 대신 Claude Code의 전체 에이전트 루프를 제공한다는 것입니다. 기능은 더 강력하지만 사용 경험도 더 무거워집니다. 빠른 인라인 지원에는 openai_compatible 방식을 선택하고, 편집기 안에서 여러 단계의 편집을 수행하는 완전한 에이전트가 필요하면 ACP 방식을 선택하세요. 대부분은 가벼운 방식으로 시작한 뒤 편집기 안에서 완전한 에이전트가 필요해지면 ACP를 도입합니다. 두 방식을 모두 준비해 두고 작업에 맞는 것을 사용할 수도 있습니다.

// 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.

자주 묻는 질문

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.