이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

사용자 정의 공급자와 게이트웨이 공급자

상태: 활성 범위: 현재 상태 최종 검토: 2026-09-06 담당: ax-code 런타임

AX Code는 표준 공급자 프로토콜로 모델과 대화합니다. OpenAI 호환(/v1/chat/completions) 또는 Anthropic 호환(/v1/messages) API를 말하는 엔드포인트는 baseURL로 가리키면 사용자 정의 공급자로 추가할 수 있습니다. 코드를 바꾸거나 내장 프리셋을 기다릴 필요가 없습니다.

여기에는 LiteLLM, one-api, new-api, Vercel AI Gateway 같은 자체 호스트 집계기와 릴레이 게이트웨이, 기업 비공개 프록시, 그 밖의 호환 서비스가 포함됩니다. AX Code는 이들을 같은 방식으로 다룹니다. 와이어 프로토콜을 말하고, URL과 키는 사용자가 제공합니다.

책임에 대한 참고. 게이트웨이는 AX Code와 업스트림 모델 사이에 있으므로, 프롬프트, 코드, 자격 증명이 그곳을 통과합니다. AX Code를 제3자나 계정을 모으는 릴레이에 가리키면, 그 운영자를 데이터에 대해 신뢰하는 책임과, 그것이 라우팅하는 모든 업스트림 공급자의 서비스 약관을 지키는 책임이 있습니다. OpenRouter 같은 내장 게이트웨이 프리셋은 같은 표준 프로토콜 경로를 사용합니다. 사용자 정의 게이트웨이 구성이 어떤 릴레이 운영자를 보증하는 것은 아닙니다.

대화형 설정

호환 게이트웨이에는 /connect → API 클라우드 공급자 → 사용자 정의 API 공급자를 사용합니다. AX Trust 게이트웨이에는 /connect → AX Trust → AX Trust 연결을 사용합니다. 기본 URL(AX Trust는 /v1 포함)과 클라이언트 API 키를 입력합니다. 편집기는 모델 ID와 메타데이터를 탐색하고 자격 증명을 암호화된 인증 저장소에 저장합니다. 탐색을 사용할 수 없으면 명시적인 모델 ID도 받을 수 있습니다. 저장된 URL에 다시 연결할 때 토큰을 비워 두면 공급자 ID와 키가 유지됩니다. AX Trust 연결은 편집과 모델 새로 고침 뒤에도 분류를 유지합니다. AX Code는 그 연결에서 세션 ID와 함께 X-AX-Prompt-Cache-Key을 보내, 게이트웨이가 세션을 자격이 있는 계정 하나에 유지할 수 있게 합니다. 끄려면 provider.<id>.options.axTrust을 false로 설정합니다. 이 헤더는 업스트림으로 전달되지 않으며 본문의 prompt_cache_key가 아닙니다.

연결된 AX Trust 공급자는 시작 때 백그라운드에서 모델 목록을 새로 고칩니다. AX Code는 기존 자격 증명으로 구성된 엔드포인트의 GET /models을 호출하고, 모델 이름, 컨텍스트/출력 한도, 추론, 도구 호출, temperature 지원, 이미지 지원을 갱신합니다. 이미지를 받는 모델은 /models에 비전 표시를 보여 주며, AX Trust가 이미지 지원을 알리는 게이트웨이 별칭도 포함됩니다. 탐색이 끝나면 TUI가 갱신됩니다. 정확한 자사 DeepSeek 모델 ID는 메타데이터가 없으면 묶인 models.dev 카탈로그로 채웁니다. 명시적인 게이트웨이 기능 플래그와 한도가 우선합니다. 알 수 없는 별칭은 이름 유사성으로 기능을 물려받지 않습니다.

새로 고침이 성공하면 런타임 목록을 바꾸고, 게이트웨이가 더 이상 알리지 않는 모델을 제거하며, 구성된 허용/차단 목록은 계속 적용합니다. 시간 초과, 오류, 비었거나 유효하지 않은 응답은 저장된 목록을 유지하고 탐색 실패를 기록합니다. 시작은 네트워크를 기다리지 않습니다. 이 새로 고침은 공급자 구성이나 자격 증명을 다시 쓰지 않습니다. 저장된 구성이 시작 폴백으로 남습니다. 일반적인 사용자 정의 API 공급자는 수동 새로 고침을 유지합니다.

공급자가 해석되는 방식

각 요청에서 AX Code는 공급자 항목에서 세 가지가 필요합니다.

npm — 와이어 프로토콜을 말하는 AI SDK 어댑터입니다. OpenAI 스타일 엔드포인트에는 @ai-sdk/openai-compatible을, Anthropic 스타일 엔드포인트에는 @ai-sdk/anthropic를 사용합니다. 묶이거나 설치할 수 있는 것은 @ai-sdk/* 어댑터뿐입니다.
options.baseURL — 게이트웨이 URL입니다. 공급자 api 필드로 폴백한 다음, 모델 자신의 api.url로 폴백합니다. ${ENV_VAR} 치환을 지원합니다.
자격 증명 — options.apiKey, 그다음 지속된 인증 저장소, 그다음 공급자의 env 변수 순으로 해석됩니다.

수동 구성에는 명시적인 models 맵도 필요합니다. 대화형 편집기는 엔드포인트나 사용자가 제공한 모델 ID에서 이 맵을 채웁니다.

전용 프라이빗 GPU 클라우드는 /connect → 프라이빗 GPU 클라우드 아래의 일급 공급자입니다. OpenAI 호환 URL과 토큰(alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti 또는 custom-private-gpu)을 붙여 넣습니다. AX Code는 GET …/models를 호출하고 배포된 모델 ID를 자동으로 사용합니다.

호스트된 GPU 카탈로그(nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra)는 API 키와 묶인 모델 스냅샷을 사용합니다. OpenCode와 같은 패턴입니다.

OpenAI 호환 게이트웨이

대부분의 집계기(LiteLLM, one-api, new-api, 무료/자체 호스트 게이트웨이)는 OpenAI 호환 표면을 노출합니다. ax-code.json에 다음을 추가합니다. 전역은 ~/.config/ax-code/ax-code.json, 프로젝트별은 저장소 루트입니다.

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

키 "my-gateway"은 /connect와 ax-code models에서 고르는 공급자 ID입니다.
models 아래의 각 키는 로컬 선택 ID입니다. 그 키와 다를 때 항목의 id를 게이트웨이가 기대하는 정확한 모델 ID로 설정합니다. 그렇지 않으면 기존 카탈로그 매핑이 없는 수동 선언 모델에는 그 키가 사용됩니다.
비밀이 커밋된 구성에 들어가지 않도록, 리터럴 키보다 ${ENV_VAR}을 선호합니다.

엔드포인트를 바꾼 뒤의 게이트웨이 모델 별칭

options.baseURL을 바꿔도 수동으로 구성한 모델 ID가 번역되지는 않습니다. 예를 들어 AX Trust 엔드포인트는 deepseek-flash을 알리고, 기존 로컬 선택은 ax-trust/deepseek-v4-flash일 수 있습니다. 로컬 키를 유지하고 provider.ax-trust.models.deepseek-v4-flash.id을 deepseek-flash로 설정합니다. 그러면 AX Code가 API 요청에 게이트웨이 ID를 보냅니다.

AX Trust DeepSeek Flash 구성 예를 보십시오. 관련된 공급자 필드를 기존 구성에 합치고, 다른 모델과 그 기능 설정은 유지합니다. 예는 {env:AX_TRUST_API_KEY}를 사용합니다. AX Code를 시작하기 전에 그 환경 변수를 설정하거나, 기존 자격 증명 구성을 유지합니다. 편집한 뒤에는 AX Code를 다시 시작합니다.

403 model is not allowed을 진단할 때는 요청의 모델 ID를 엔드포인트의 인증된 GET /models 응답과 비교합니다. 모델 목록 요청이 성공했다고 모델을 실행할 권한이 확립되지는 않습니다. 정확한 ID가 여전히 실패하면 게이트웨이의 키/모델 권한을 확인합니다.

Anthropic 호환 게이트웨이

/v1/messages(Claude API 형태)를 노출하는 릴레이는 Anthropic 어댑터를 사용합니다.

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

일부 Anthropic 형태 릴레이는 Claude 환경 변수도 직접 존중합니다. 구성을 편집하지 않는 빠른 헤드리스 실행에는 다음을 설정할 수 있습니다.

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

게이트웨이가 선별된 모델 목록과 함께 선택 가능한 공급자로 나타나게 하려면 구성 항목을 여전히 권장합니다.

모델 필드

모델 항목은 레지스트리 스키마를 다시 사용합니다. 사용자 정의 엔드포인트에서 유용한 필드는 다음과 같습니다.

필드	의미
`name`	모델 선택기의 표시 이름
`tool_call`	모델이 도구/함수 호출을 지원하는지(도구에 필요)
`reasoning`	모델이 확장 추론을 내보내는지
`attachment`	모델이 이미지/파일 첨부를 받는지
`limit`	예산에 쓰는 `{ context, output }` 토큰 한도
`modalities`	선택적 `{ input, output }` 배열(`text`, `image`, `pdf` 등)

기능 플래그는 업스트림 모델이 실제로 지원하는 것에 맞춥니다. AX Code는 이것을 써서 도구 호출, 첨부, 컨텍스트 예산을 제한합니다.

확인

구성을 저장한 뒤:

ax-code models은 공급자가 노출하는 모든 모델을 나열합니다.
TUI 안의 /connect은 공급자를 보여 주며, env 키를 options.apiKey 대신 썼다면 인증할 수 있게 합니다.

모델이 없으면 공급자 ID, 모델 키, 게이트웨이가 baseURL에서 도달 가능한지 확인합니다.

문제 해결

인증 오류 — 자격 증명 해석 순서를 확인합니다. options.apiKey가 우선하고, 그렇지 않으면 env/인증 저장소 키가 사용됩니다.
멈춘 스트림 — 게이트웨이가 때로 SSE를 버퍼링합니다. 공급자에서 options.chunkTimeout(청크별)와 options.timeout(요청 전체)를 조정합니다.
거부된 도구 호출 — 모델에 "tool_call": true을 설정하고, 게이트웨이 뒤의 업스트림 모델이 실제로 도구를 지원하는지 확인합니다.