작성자 주: Zed의 세 가지 Agent 경로를 구분한 뒤, OpenAI-compatible과 Anthropic-compatible 두 가지 사용자 정의 Provider로 APIYI를 Zed에 연결하고 Base URL, 모델 ID, 가격, 문제 해결 요점을 설명합니다.
Zed에서 Agent 패널이나 Inline Assistant로 코드를 작성하다가 다른 모델로 바꾸고 싶은데, 설정 화면에 LLM Providers, External Agents, 터미널 스레드 등 여러 진입점이 보여서 API 키를 어디에 넣어야 할지 헷갈리는 경우가 많아요. 더 흔한 상황은 서드파티 게이트웨이를 입력했더니 계속 404나 인증 실패가 나는 경우죠. 이 글에서는 Zed 사용자 정의 Provider(OpenAI-compatible / Anthropic-compatible)로 서드파티 모델 게이트웨이에 연결하는 전체 방법을 APIYI를 예로 들어 설정 흐름을 끝까지 짚어봅니다.
이 글은 “설정만 복사해 붙여넣으면 끝”인 또 하나의 빠른 참고서가 아니에요. 먼저 Zed의 세 가지 AI 경로가 각각 어떤 모델 연결 범위를 갖는지 설명하고, 그다음 그대로 따라 할 수 있는 두 가지 경로를 제시해요. Base URL에 /v1을 언제 붙이고 언제 붙이지 않는지, 이 가장 실수하기 쉬운 부분은 따로 설명합니다.
핵심 가치: 이 글을 읽고 나면 내가 바꿔야 할 설정이 어느 계층인지 판단할 수 있고, 5분 안에 Zed Agent에서 claude-opus-5-5, claude-sonnet-5-5 같은 모델을 쓸 수 있어요. 문제가 생기면 어느 항목부터 확인해야 하는지도 알게 됩니다.
Zed 모델 변경 핵심 포인트: 먼저 세 가지 Agent 경로를 구분하세요
Zed는 Atom / Tree-sitter 개발진이 만든 고성능 다중 사용자 협업 에디터예요. 2026-11-13 기준 GitHub 저장소 zed-industries/zed의 스타는 약 94,884개입니다(GitHub API 관측). 공식 releases 페이지를 보면 2026-11-11자 안정 버전은 1.28.1, 같은 날 Preview는 1.29.1이에요. macOS, Linux, Windows 모두 바로 다운로드할 수 있고, Web 버전은 아직 정식으로 사용할 수 없어요.
Zed에서 모델을 바꾸기 전에 먼저 알아야 할 점이 있어요. 공식 문서는 AI 기능을 세 가지 경로로 나누는데, 경로마다 모델 연결 방식과 인증 방식이 모두 달라요. 위치를 잘못 채우면 설정이 적용되지 않고, Key도 다른 경로에서 읽히지 않아요.
| 경로 | 모델은 어디서 오나 | 인증은 누가 관리하나 | 대표 용도 |
|---|---|---|---|
| Zed Agent | LLM Providers(Zed 호스팅, 벤더 Key, 구독, 게이트웨이, 로컬 모델) | Zed 자체, Key는 시스템 키체인에 저장 | Agent 패널, Inline Assistant, 내장 도구 / profiles / skills / MCP |
| External Agents(ACP) | 외부 Agent가 직접 모델 선택 | 외부 Agent가 직접 관리 | Zed 스레드에서 Claude Agent, Codex, OpenCode, Copilot, Cursor 등 실행 |
| Terminal Threads | 당신이 실행하는 CLI / TUI가 결정 | CLI 자체 설정 | 터미널 스레드에서 각종 Agent CLI를 직접 실행 |
Zed Agent와 External Agent의 접속 경계
“Zed Agent의 모델 바꾸기”란 LLM Providers, 즉 API Access 계층을 설정하는 것을 말하며, 이 글의 주제예요. 공식 지원하는 1급 벤더는 Anthropic, OpenAI, Google AI, Mistral, DeepSeek, xAI, OpenCode이고, 추가로 Anthropic-compatible과 OpenAI-compatible 두 가지 사용자 정의 엔드포인트를 제공해요. 서드파티 게이트웨이는 이 두 사용자 정의 엔드포인트를 통해 연결돼요.
패널에서 그냥 Claude Agent나 OpenCode를 쓰고 싶다면 그건 External Agent에 속하고, Agent Client Protocol(ACP)을 사용해요. 이 경우 스레드는 Zed가 관리하지만, 런타임과 인증, 모델 선택은 보통 외부 Agent가 직접 담당해요. LLM Providers에 입력한 Key는 자동으로 공유되지 않아요. Claude Agent는 자체 스레드에서 /login을 실행해야 해요. 외부 Agent는 명령 팔레트 zed: acp registry로 레지스트리를 열어 설치할 수 있어요. 공식 문서에 따르면 Zed는 External Agents에 대해 별도로 과금하지 않으며, 청구는 Agent 제공업체에서 이뤄져요.
Zed 커스텀 Provider 핵심 설정 포인트
두 가지 커스텀 엔드포인트의 차이는 주로 요청 형식에 있어요. OpenAI-compatible은 Chat Completions를 사용하고, Anthropic-compatible은 Messages API(/v1/messages)를 사용해요. 이 차이가 Base URL 작성법을 직접 결정하고, Prompt Cache 과금을 쓸 수 있는지도 결정해요.
| 설정 항목 | OpenAI-compatible | Anthropic-compatible |
|---|---|---|
| 요청 형식 | /v1/chat/completions |
/v1/messages |
| APIYI api_url | https://api.apiyi.com/v1 |
https://api.apiyi.com(/v1 없이) |
| 모델 필드 | available_models[].name + max_tokens |
available_models |
| 기능 스위치 | 기본값 tools=true, images=false, chat_completions=true | capabilities.prompt_caching 설정 가능 |
| 캐시 과금 | APIYI 문서상 적용되지 않음 | 네이티브 Messages 형식에서 적용됨 |
| 적합한 시나리오 | 하나의 Provider로 여러 모델을 연결하고 싶을 때 | Claude를 주력으로, 긴 컨텍스트, 캐시가 필요할 때 |
Base URL은 왜 하나는 /v1을 붙이고 하나는 안 붙일까
APIYI Base URL FAQ(문서 확인 2026-11-13)에 따르면, OpenAI 호환 클라이언트는 api_url 뒤에 /chat/completions를 직접 붙이기 때문에 api_url을 /v1 단계까지 써야 해요. Anthropic 쪽 클라이언트는 스스로 /v1/messages를 붙이므로 루트 도메인만 입력할 수 있어요. 만약 https://api.apiyi.com/v1이라고 쓰면 최종 요청이 /v1/v1/messages가 되어 바로 404를 반환해요.
두 가지 더 주의할 점이 있어요. Zed의 API Key는 시스템 키체인에 저장되고 settings.json에 기록되지 않아요. 해당 환경 변수가 비어 있지 않으면 환경 변수가 키체인보다 우선 적용돼요. 또 Responses 인터페이스만 지원하는 모델은 capabilities.chat_completions를 false로 설정해야 해요. 그렇지 않으면 Zed가 Chat Completions로 호출해요.
Zed에서 APIYI 연결 빠른 시작
아래 두 가지 경로 중 하나만 선택해도 되고, 둘 다 설정해서 모델 선택기에서 전환할 수도 있어요. 시작하기 전에 먼저 Key를 준비하세요.
🚀 빠른 시작: 로그인 후 APIYI 토큰 페이지
api.apiyi.com/token에서 토큰을 생성하세요. Zed 전용으로 따로 만들어 두면 사용량 확인과随时 폐기가 쉬워요. 빠른 시작 문서 docs.apiyi.com/getting-started에서는 skill.md / llms.txt도 제공하니, Agent가 플랫폼 설명을 읽도록 하기에 편리해요.
경로 A: OpenAI-compatible 엔드포인트로 Zed 연결
- Agent 설정 열기: 명령 팔레트에서
agent: open settings를 실행하세요. 버전에 따라 인터페이스 진입점 이름이 조금 다를 수 있으니, AI / Agent 설정 페이지의 LLM Providers 블록을 기준으로 하세요. - LLM Providers 블록에서 Add Provider를 클릭하고, 유형은 OpenAI-compatible을 선택하세요.
- Provider 이름은 직접 정하세요. 예를 들어
apiyi라고 하면 settings.json의language_models.openai_compatible.apiyi에 해당해요. - API URL에는
https://api.apiyi.com/v1을 입력하세요. 여기서는 반드시/v1을 붙여야 해요. APIYI의 OpenAI 호환 페이지에서도 이렇게 안내하고 있어요. - API Key에는 방금 생성한 토큰을 붙여넣으세요. Zed가 이 토큰을 시스템 키체인에 저장해줘요.
- 모델 추가: name에는 APIYI 모델 목록에 있는 실제 ID를 입력하세요. 예를 들어
claude-opus-5-5,claude-sonnet-5-5이고,claude-fable-5-2도 추가할 수 있어요.max_tokens는 모델 문서에 따라 입력하세요. 확실하지 않으면 처음에는 보수적인 값을 쓰고, 정상 동작을 확인한 뒤에 늘리세요. - 능력 토글은 기본값 그대로 두면 돼요(tools=true). 이미지를 보낼 때만 images를 직접 켜세요.
- Agent 패널로 돌아가서 모델 선택기에서
apiyi나 모델명을 검색하세요. 최근 버전의 모델 선택기는 퍼지 검색을 지원하니, 선택한 후 메시지를 하나 보내서 확인해보세요.
이 경로의 장점은 Provider 하나로 여러 모델을 붙일 수 있다는 거예요. APIYI 문서에 따르면 OpenAI 호환 엔드포인트 /v1/chat/completions는 모델 문자열 한 군데만 바꾸면 모델을 교체할 수 있어요.
경로 B: Anthropic-compatible 엔드포인트로 Zed 연결하기
- 마찬가지로 LLM Providers → Add Provider로 들어간 뒤, 유형은 Anthropic-compatible을 선택해요.
- API URL에는
https://api.apiyi.com을 입력하는데, 루트 도메인만 적고 /v1은 붙이지 않아요. 실제 요청은 APIYI의 Anthropic 네이티브 엔드포인트인https://api.apiyi.com/v1/messages로 전달돼요. - 같은 토큰을 붙여넣거나, 아니면 전용 토큰을 따로 하나 만들어요.
- available_models에
claude-opus-5-5,claude-sonnet-5-5같은 ID를 추가해요. - 긴 컨텍스트 대화가 캐시에 걸리길 원한다면
capabilities.prompt_caching을 켜요. APIYI Claude 기능 페이지 설명에 따르면, 캐시 과금은 네이티브 Messages 형식에서만 적용돼요. - 모델 선택기에서 해당 모델을 고르고 메시지를 하나 보내서 테스트해요.
💡 선택 가이드: 평소 Claude를 주력으로 쓰고, 대화가 길며, 같은 파일 묶음을 자주 반복해서 읽는다면 경로 B가 더 이득이에요. 여러 모델 사이를 자주 오가야 한다면 경로 A가 더 간편하고요. 두 경로 모두 같은 APIYI 토큰을 쓸 수 있으니, Zed 모델 선택기에서 작업에 따라 전환하면 돼요.
Claude 모델 가격 참고(데이터 기준일 2026-11-13)
아래 데이터는 APIYI 모델 총표에서 가져왔으며, 2026-11-13 문서 기준으로 확인한 내용이에요. 단위는 미국 달러 / 1M tokens당이고, 사용량 기반으로 과금돼요.
| 모델 ID | 입력 | 출력 | 캐시 읽기 | 지원 엔드포인트 | 사용 가능 플랫폼 |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0.2 | chat + messages | APIYI apiyi.com |
claude-opus-5-5-thinking |
opus-5-5와 동일 | opus-5-5와 동일 | opus-5-5와 동일 | 총표 기준 | APIYI apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0.1 | 총표 기준 | APIYI apiyi.com |
claude-fable-5-2 |
$8 | $40 | $0.2 | 총표 기준 | APIYI apiyi.com |
모델과 가격은 플랫폼 모델 목록을 기준으로 해요. 설정 전에 docs.apiyi.com/models를 열어 당일 수치와 그룹을 확인할 수 있어요(총표의 claude-opus-5-5 항목에는 ClaudeCode, Claude_Reverse, Claude_Enterprise, Default, SVIP 등의 그룹이 있어요).
claude-opus-5-5 사용 제한과 관련해 APIYI 출시 공지(2026-09-23)에서는 세 가지를 언급했어요. 사고(thinking)를 disabled로 설정할 수 없고, tool_choice를 any / tool로 설정하면 400이 반환되며, effort 기본값은 medium이에요. Zed Agent에서 도구를 호출할 때 400이 발생한다면 이 항목들부터 확인하세요.
Zed 사용자 정의 엔드포인트에서 자주 발생하는 오류 해결
Custom Provider에서 오류가 날 때, 대부분의 문제는 URL, Key, 모델 이름 이 세 군데에서 발생해요. 아래 표는 발생 빈도 순으로 정리한 것이니 하나씩 점검해 보세요.
| 증상 | 흔한 원인 | 해결 방법 |
|---|---|---|
| 404 Not Found | Anthropic-compatible에 /v1을 넣어 경로가 /v1/v1/messages가 됨 |
루트 도메인 https://api.apiyi.com으로 되돌리기 |
| 404 / 경로 오류 | OpenAI-compatible에서 /v1 누락 |
https://api.apiyi.com/v1로 수정 |
| 401 / 인증 실패 | 토큰 오류, 삭제됨, 또는 환경 변수가 키체인 값을 덮어씀 | api.apiyi.com/token에서 다시 확인하고 충돌하는 환경 변수를 비우기 |
| 모델 없음 | ID 오타 또는 별칭 사용 | docs.apiyi.com/models에서 원본 ID를 그대로 복사 |
| 400(도구 호출) | tool_choice가 any / tool이거나, 사고(thinking) 비활성화 시도 |
공개된 동적 안내에 맞춰 조정 |
| 이미지 무효 | OpenAI-compatible은 기본값이 images=false | capabilities에서 images를 켜기 |
| Responses만 지원하는 모델에서 오류 | 여전히 Chat Completions로 호출 | capabilities.chat_completions를 false로 설정 |
🎯 문제 해결 팁: 404가 나오면 Zed 설정의 api_url과 APIYI Base URL FAQ(docs.apiyi.com/faq/base-url-config)를 한 글자씩 대조해 보세요. 대부분의 문제는
/v1을 한 번 더 쓰거나 빠뜨린 데서 비롯돼요.
Zed 커스텀 Provider 사용 시 유의 사항
- 비공식 호스팅: OpenAI-compatible / Anthropic-compatible 커스텀 Provider는 Zed가 제공하는 범용 연동 기능이며, 서드파티 게이트웨이는 Zed의 공식 호스팅 서비스가 아닙니다. 서비스에 문제가 생기면 게이트웨이 쪽에 문의해야 해요.
- 키와 과금은 본인 책임: 토큰과 사용량 과금은 모두 본인 계정 아래에서 이루어집니다. Zed용 토큰을 따로 만들어 두고 주기적으로 사용량을 확인하는 걸 권장하며, Key를 settings.json에 적어 넣은 뒤 저장소에 커밋하는 일은 피해야 해요. Zed는 기본적으로 키체인에 저장하기 때문에 이런 위험은 애초에 줄어듭니다.
- External Agent의 약관은 제공자 몫: Claude Agent, Codex 같은 외부 Agent의 구독, 할당량, 이용 약관은 각 제공자가 정하며, Zed Agent의 Provider 설정과는 서로 독립적이에요.
- 버전 차이: 이 글의 화면 설명은 1.28.x / 1.29.x 공식 문서와 releases 정보를 기준으로 합니다(확인일 2026-11-13). 이후 버전에서는 메뉴 이름이 바뀔 수 있어요.
자주 묻는 질문 (FAQ)
Q1: Zed의 OpenAI 호환 엔드포인트가 무엇인가요?
LLM Providers에 있는 커스텀 Provider 유형 중 하나예요. 서버 쪽에서 Chat Completions 인터페이스를 구현하기만 하면 api_url과 모델 목록으로 Zed Agent에 연결할 수 있고, Zed의 공식 지원을 기다릴 필요가 없어요.
Q2: LLM Providers에 입력한 Key를 Claude Agent에서 바로 쓸 수 있나요?
아니요. Claude Agent는 External Agent에 속하고 인증을 자체적으로 관리하기 때문에, 해당 스레드에서 `/login`을 실행해야 해요. LLM Providers에 넣은 Key는 Zed Agent에서만 쓰입니다.
Q3: OpenAI-compatible과 Anthropic-compatible 중 뭘 골라야 하나요?
주로 Claude를 쓰고 캐시 과금이 필요하면 Anthropic-compatible, 하나의 Provider로 여러 모델을 묶고 싶으면 OpenAI-compatible을 선택하세요. APIYI 문서에 따르면 캐시 과금은 네이티브 Messages 형식에서만 적용됩니다.
Q4: 모델 ID에는 무엇을 입력해야 하나요?
플랫폼 모델 총표에 있는 원본 ID를 그대로 입력하세요. 예를 들어 `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-2` 같은 식이에요. docs.apiyi.com/models에서 직접 복사하는 걸 권장하며, 손으로 입력하다 오타가 나면 “모델이 존재하지 않음” 오류가 날 수 있어요.
Q5: 설정 후 계속 404가 뜨면 어떻게 확인해야 하나요?
먼저 `/v1`을 확인하세요. OpenAI-compatible은 붙여야 하고, Anthropic-compatible은 붙이면 안 됩니다. 경로에 문제가 없다면 모델 ID가 APIYI 모델 목록과 일치하는지 점검해 보세요.
Q6: API Key는 어디에 저장되나요? 저장소에 동기화될 수 있나요?
Zed는 Key를 시스템 키체인에 저장하고 settings.json에는 쓰지 않기 때문에, 설정 파일을 공유해도 Key가 함께 나가지 않아요. 다만 같은 이름의 환경 변수가 비어 있지 않으면 키체인보다 우선하니, 401을 디버깅할 때 환경 변수도 잊지 말고 확인하세요.
Q7: 이 설정에는 어떤 알려진 제약이 있나요?
OpenAI-compatible은 기본적으로 이미지 기능이 꺼져 있고, `claude-opus-5-5`는 사고(thinking)를 끌 수 없으며, `tool_choice`를 any / tool로 설정하면 400이 반환됩니다. 또한 커스텀 Provider는 Zed의 공식 호스팅 서비스가 아니므로 안정성은 게이트웨이 쪽에 달려 있어요.
Zed에서 APIYI 연동하기 핵심 요점 Key Takeaways
- 경로 먼저 구분: Zed Agent는 LLM Providers를 사용하고, External Agent는 인증을 자체적으로 관리해요.
- 두 가지 엔드포인트: OpenAI-compatible은 chat, Anthropic-compatible은 messages를 사용해요.
- URL 규칙: OpenAI 호환은
/v1을 입력하고, Claude 원본은 루트 도메인만 입력해요. - 모델 ID: APIYI 모델 총표에서
claude-opus-5-5같은 원본 ID를 그대로 복사해요. - 캐시 과금: 캐시가 필요할 때는 Anthropic-compatible을 사용하고 prompt_caching을 켜요.
- 문제 해결 순서:
/v1, 토큰, 모델 ID, 도구 파라미터를 차례대로 확인해요. - 시작 방법: api.apiyi.com/token에서 전용 토큰을 만들면 5분 만에 설정을 끝낼 수 있어요.
정리
Zed에서 모델을 바꿀 때 핵심은 어느 계층을 바꿔야 하는지 확인하는 거예요.
- Zed Agent 모델 변경: LLM Providers에서 Add Provider로 OpenAI-compatible 또는 Anthropic-compatible 엔드포인트를 추가해요.
- External Agent: Claude Agent, OpenCode 등은 자체적으로 인증하며, Key는 Zed Agent와 공유하지 않아요.
- Base URL: OpenAI 호환은
https://api.apiyi.com/v1, Anthropic 호환은https://api.apiyi.com을 입력해요./v1을 더 쓰거나 빼면 404가 나요.
설정하기 전에 docs.apiyi.com/models에서 당일 모델과 가격을 먼저 확인하고, 토큰 페이지에서 Zed 전용 Key를 만드는 걸 권장해요. 먼저 claude-sonnet-5-5로 동작을 확인한 뒤, 작업에 따라 claude-opus-5-5로 전환해요. APIYI apiyi.com을 통해 같은 토큰으로 두 Provider에서 효과를 비교해볼 수 있어요.
📚 참고 자료
- Zed GitHub 리포지토리: 소스 코드 및 스타 수 관찰(2026-11-13)
- 링크:
github.com/zed-industries/zed -
설명: 라이선스는 주로 GPL-3.0-or-later이며, Apache-2.0 구성 요소를 포함해요
-
Zed AI Overview: 세 가지 AI 경로에 대한 공식 설명
- 링크:
zed.dev/docs/ai/overview -
설명: Zed Agent, External Agents, Terminal Threads의 경계
-
Zed Use API Access: 사용자 지정 Provider 구성
- 링크:
zed.dev/docs/ai/use-api-access -
설명: OpenAI 호환 / Anthropic 호환 필드 및 키체인 저장
-
Zed External Agents: ACP 외부 Agent
- 링크:
zed.dev/docs/ai/external-agents -
설명: Claude Agent, Codex, OpenCode 등의 연동 방식
-
Zed Releases: 버전 업데이트 기록
- 링크:
zed.dev/releases/stable -
설명: 1.28.1 안정판 및 Preview 업데이트 내용
-
APIYI 모델 총표: 모델 ID 및 가격
- 링크:
docs.apiyi.com/models.md -
설명: 입력 / 출력 / 캐시 읽기 가격, 당일 목록 기준
-
APIYI Base URL 구성 FAQ: /v1 규칙
- 링크:
docs.apiyi.com/faq/base-url-config.md -
설명: OpenAI 호환 및 Claude 네이티브 Base URL 작성 방식의 차이
-
APIYI Claude 기능 페이지: 네이티브 및 호환 엔드포인트
- 링크:
docs.apiyi.com/api-capabilities/claude.md -
설명: 캐시 과금은 Messages 형식에서만 적용돼요
-
APIYI claude-opus-5-5 출시 소식: 사용 제한
- 링크:
docs.apiyi.com/live/2026-09/claude-opus-5-5.md - 설명: 사고(thinking), tool_choice, effort 기본값 설명
작성자: APIYI 기술 팀
기술 지원: 구성 중 문제가 발생하면 docs.apiyi.com 문서 센터를 확인하거나 APIYI 공식 웹사이트 첫 페이지를 통해 문의해 주세요
