AI 코딩 에이전트 및 하네스
Claude Code, Codex CLI, OpenClaw, Cline, Cursor 등 25개 이상의 코딩 에이전트를 같은 세 단계로 게이트웨이에 연결하세요 — 각각의 정확한 구성 대상과 키 이름을 함께 정리했습니다.
모든 AI 코딩 에이전트는 어딘가에서 base URL과 API 키를 읽습니다 — 환경 변수, 구성 파일, 설정 패널. 이 페이지는 각 하네스가 어디서 읽는지, 어떤 프로토콜을 사용하는지, 실제로 사람을 걸려 넘어지게 하는 주의사항 하나를 정리합니다. 복사해 붙일 수 있는 전체 구성은 문서에 있습니다.
base_url을 게이트웨이로 지정
기본값은 https://your-gateway.gatellm.io 입니다 — /v1 포함 여부는 SDK마다 다릅니다(각 예시에 정확한 값을 표기).
게이트웨이 액세스 키로 교체
업스트림 sk-… 키가 아닙니다 — 같은 액세스 키가 SDK가 기대하는 헤더에 맞춰 들어갑니다.
게이트웨이 모델 이름 사용
콘솔에서 구성한 이름을 쓰세요 — 벤더의 공식 이름이 아닙니다.
Authorization: Bearer <key>x-api-key: <key>x-goog-api-key: <key>하네스 호환성 매트릭스
| 하네스 | 프로토콜 | 지원 | 구성 대상 | 키 이름 / 설정 | 문서 |
|---|---|---|---|---|---|
| 터미널 에이전트 | |||||
| Claude Code | Anthropic | 네이티브 | env vars | ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_MODEL | GitHub 구성 예시 ↗ · 문서 |
| Codex CLI | OpenAI Responses | 네이티브 | ~/.codex/config.toml | base_url, env_key, wire_api | GitHub 구성 예시 ↗ · 문서 |
| Gemini CLI | Gemini | 네이티브 | env vars | GOOGLE_GEMINI_BASE_URL, GEMINI_API_KEY | GitHub 구성 예시 ↗ · 문서 |
| OpenClaw | OpenAI / Anthropic-compatible | OpenAI 호환 | openclaw.json | models.providers.<id>.baseUrl, models.providers.<id>.apiKey | 문서 |
| opencode | OpenAI-compatible | OpenAI 호환 | opencode.json | provider.<id>.options.baseURL | 문서 |
| Crush | OpenAI / Anthropic-compatible | OpenAI 호환 | crush.json | providers.<id>.base_url, providers.<id>.type | 문서 |
| Factory Droid | OpenAI / Anthropic-compatible | OpenAI 호환 | ~/.factory/settings.json | customModels[].baseUrl, customModels[].provider | 문서 |
| Goose | OpenAI-compatible | OpenAI 호환 | env vars | OPENAI_HOST, OPENAI_BASE_PATH, OPENAI_API_KEY | 문서 |
| Aider | OpenAI-compatible (LiteLLM) | OpenAI 호환 | env vars | OPENAI_API_BASE | 문서 |
| Qwen Code | OpenAI-compatible | OpenAI 호환 | env vars | OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL | 문서 |
| OpenHands | OpenAI-compatible (LiteLLM) | OpenAI 호환 | ~/.openhands/settings.json | base_url, model openai/ prefix | 문서 |
| Kimi Code CLI | OpenAI / Anthropic | OpenAI 호환 | config.toml | providers | 문서 |
| Plandex | OpenAI-compatible | OpenAI 호환 | custom models JSON | baseUrl | 문서 |
| SWE-agent | OpenAI-compatible (LiteLLM) | OpenAI 호환 | env vars | OPENAI_BASE_URL | 문서 |
| Grok Build | OpenAI-compatible | OpenAI 호환 | config.toml | custom models | 문서 |
| Mistral Vibe | OpenAI-compatible | OpenAI 호환 | ~/.vibe/config.toml | providers | 문서 |
| MiMo Code | OpenAI-compatible | OpenAI 호환 | /connect custom provider | base URL, API key | 문서 |
| ForgeCode | OpenAI / Anthropic | OpenAI 호환 | setup wizard | base URL | 문서 |
| Codebuff | OpenAI-compatible | OpenAI 호환 | settings | base URL, API key | 문서 |
| IDE 및 확장 | |||||
| Cline | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | 문서 |
| Roo Code | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | 문서 |
| Kilo Code | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | 문서 |
| Continue | OpenAI-compatible | OpenAI 호환 | config.yaml | models[].apiBase | 문서 |
| Zed | OpenAI-compatible | OpenAI 호환 | settings.json | language_models.openai_compatible.<id>.api_url | 문서 |
| Cursor | OpenAI | 부분 지원 | Settings → Models → Override OpenAI Base URL | Override OpenAI Base URL | 문서 |
| Windsurf | OpenAI-compatible | OpenAI 호환 | Settings → Models → BYOK / custom | Base URL, API Key | 문서 |
| GitHub Copilot (BYOK) | OpenAI-compatible | OpenAI 호환 | Manage Models → OpenAI-compatible | Base URL, API Key | 문서 |
| 관리형 플랫폼 | |||||
| Warp | OpenAI / Anthropic / Gemini (BYOK) | 부분 지원 | Settings → BYOK | BYOK API keys | 문서 |
| Amazon Q Developer CLI | MCP | 사용자 정의 엔드포인트 불가 | MCP server | — | 문서 |
| Devin | — | 사용자 정의 엔드포인트 불가 | — | — | 문서 |
게이트웨이 모델 이름을 무엇으로 할까
일부 하네스는 자체 모델 ID를 고정해 그대로 보냅니다. 게이트웨이 모델 이름이 다르면 첫 호출이 404가 납니다. 맞추는 방법은 두 가지입니다:
게이트웨이 모델 이름을 하네스가 요청하는 이름과 정확히 같게 지정 — 추가 구성 없음.
또는 하네스의 모델 환경 변수(예: ANTHROPIC_MODEL)로 게이트웨이 이름을 쓰도록 재정의.
주의사항
Claude Code는 구성된 기본값(예: claude-opus-5 또는 claude-sonnet-5)을 보냅니다 — 게이트웨이 이름이 아닙니다. 게이트웨이 모델 이름을 하네스가 요청하는 이름과 정확히 같게 지정하거나, 하네스의 모델 환경 변수(예: ANTHROPIC_MODEL)를 게이트웨이 이름으로 설정하세요. 불일치 시 첫 메시지에서 404 model_not_found가 발생합니다.
Anthropic 스타일 클라이언트의 base URL은 게이트웨이 루트(/v1 없음)로 지정합니다 — 클라이언트가 스스로 /v1/messages를 붙이기 때문입니다. 여기에 /v1을 붙이면 경로 세그먼트가 두 번 쌓입니다.
Codex CLI는 사용자 정의 [model_providers.*] 블록에 wire_api = "responses"를 요구합니다. 게이트웨이는 /v1/responses를 네이티브로 구현합니다 — base_url을 여기로 지정하고 env_key를 게이트웨이 액세스 키로 설정하세요.
Aider, OpenHands, SWE-agent는 LiteLLM 위에 있습니다: OPENAI_API_BASE를 게이트웨이로 설정하고 모델 이름에 openai/ 접두사를 붙이세요(예: openai/gateway-model-name). 그러면 LiteLLM이 게이트웨이를 OpenAI 호환 엔드포인트로 라우팅합니다.
Codex, Gemini CLI, Qwen Code는 기본적으로 벤더의 OAuth / 구독 로그인을 사용합니다. 게이트웨이를 경유하려면 API 키 인증으로 전환해야 합니다(키와 base URL을 명시적으로 설정) — 그렇지 않으면 에이전트가 게이트웨이를 완전히 우회합니다.
Cline / Roo / Kilo 등은 모델 이름으로 도구 호출과 비전 기능을 판단합니다. 사용자 정의 게이트웨이 이름은 함수 호출을 비활성화할 수 있습니다 — 도구 호출이 실패하면 클라이언트의 기능 탐지 규칙을 확인하거나, 알려진 계열과 일치하도록 모델 이름을 지정하세요.
업스트림 추론이 길어지면 게이트웨이가 SSE :keep-alive 주석 줄을 내보내며(무해합니다 — :로 시작하는 줄은 건너뛰세요), 스트림이 중간에 끊기면 오류를 내는 대신 _gateway_warning 필드를 삽입합니다. 덕분에 Claude Code 같은 하네스가 대화 전체를 중단하지 않습니다.
자동 모드에서 Claude Code는 잠재적으로 위험한 작업 전에 서버 측 판정(요청의 safeguards 필드)을 기다립니다. 업스트림이 공식 Anthropic이면 판정이 같은 요청 안에서 생성되고 게이트웨이는 이를 그대로 전달합니다. 필드를 무시하는 제3자 업스트림이면 게이트웨이가 대신 응답하며 — 출하 기본값(allow_all)은 모든 작업을 허용하므로 호출을 그냥 두는 것보다 더 관대합니다. 해당 업스트림의 extra_config에 "anthropic_server_safeguards": "upstream"을 작성하면 경로를 업스트림으로 되돌릴 수 있습니다. 콘솔 설정은 관리자 전용입니다.
# Every agent is one base_url + one access key away
export ANTHROPIC_BASE_URL="https://your-gateway.gatellm.io" # Anthropic agents: root (no /v1)
export ANTHROPIC_API_KEY="<gateway access key>"
export OPENAI_API_BASE="https://your-gateway.gatellm.io/v1" # OpenAI-compatible agents: /v1
export OPENAI_API_KEY="<gateway access key>"
# Codex CLI (~/.codex/config.toml) speaks the Responses protocol
# [model_providers.gatellm]
# base_url = "https://your-gateway.gatellm.io/v1"
# wire_api = "responses"