# AI 코딩 에이전트 및 하네스 - GateLLM

> Claude Code, Codex CLI, OpenClaw, Cline, Cursor, Zed, Goose, Aider 등 25개 이상 코딩 에이전트를 GateLLM에 연결하세요 — 각 하네스의 base URL, 구성 대상, 주의사항을 한곳에 정리했습니다.

표준 링크: https://www.gatellm.io/ko/coding-agents/

## AI 코딩 에이전트 및 하네스
Claude Code, Codex CLI, OpenClaw, Cline, Cursor 등 25개 이상의 코딩 에이전트를 같은 세 단계로 게이트웨이에 연결하세요 — 각각의 정확한 구성 대상과 키 이름을 함께 정리했습니다.
모든 AI 코딩 에이전트는 어딘가에서 base URL과 API 키를 읽습니다 — 환경 변수, 구성 파일, 설정 패널. 이 페이지는 각 하네스가 어디서 읽는지, 어떤 프로토콜을 사용하는지, 실제로 사람을 걸려 넘어지게 하는 주의사항 하나를 정리합니다. 복사해 붙일 수 있는 전체 구성은 문서에 있습니다.
## 게이트웨이 모델 이름을 무엇으로 할까
일부 하네스는 자체 모델 ID를 고정해 그대로 보냅니다. 게이트웨이 모델 이름이 다르면 첫 호출이 404가 납니다. 맞추는 방법은 두 가지입니다:
게이트웨이 모델 이름을 하네스가 요청하는 이름과 정확히 같게 지정 — 추가 구성 없음.
또는 하네스의 모델 환경 변수(예: ANTHROPIC_MODEL)로 게이트웨이 이름을 쓰도록 재정의.
## 모든 AI 코딩 에이전트를 게이트웨이로 연결하세요
```
# 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"
```
### `Authorization: Bearer <key>`
- SDK / 프레임워크: OpenAI · DashScope · 범용
- Bearer 접두사는 대소문자를 구분하지 않습니다

### `x-api-key: <key>`
- SDK / 프레임워크: Anthropic SDK
- Authorization도 허용됩니다

### `x-goog-api-key: <key>`
- SDK / 프레임워크: Gemini SDK
- Authorization도 허용됩니다

## 하네스 호환성 매트릭스

### 터미널 에이전트
Claude Code, Codex CLI, Gemini CLI, OpenClaw, opencode, Crush, Droid, Goose, Aider, Qwen Code, OpenHands, Kimi Code, Plandex, SWE-agent, Grok Build, Mistral Vibe, MiMo Code, ForgeCode, Codebuff
| 하네스 | 프로토콜 | 지원 | 구성 대상 | 키 이름 / 설정 | 문서 |
| --- | --- | --- | --- | --- | --- |
| Claude Code | Anthropic | 네이티브 | env vars | ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_MODEL | https://docs.gatellm.io/en/quickstart/claude-code-via-gateway |
| Codex CLI | OpenAI Responses | 네이티브 | ~/.codex/config.toml | base_url, env_key, wire_api | https://docs.gatellm.io/en/reference/clients-and-gateway-diffs |
| Gemini CLI | Gemini | 네이티브 | env vars | GOOGLE_GEMINI_BASE_URL, GEMINI_API_KEY | https://docs.gatellm.io/en/reference/clients-and-gateway-diffs |
| OpenClaw | OpenAI / Anthropic-compatible | OpenAI 호환 | openclaw.json | models.providers.<id>.baseUrl, models.providers.<id>.apiKey | https://docs.gatellm.io/en/quickstart/anthropic-interop |
| opencode | OpenAI-compatible | OpenAI 호환 | opencode.json | provider.<id>.options.baseURL | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Crush | OpenAI / Anthropic-compatible | OpenAI 호환 | crush.json | providers.<id>.base_url, providers.<id>.type | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Factory Droid | OpenAI / Anthropic-compatible | OpenAI 호환 | ~/.factory/settings.json | customModels[].baseUrl, customModels[].provider | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Goose | OpenAI-compatible | OpenAI 호환 | env vars | OPENAI_HOST, OPENAI_BASE_PATH, OPENAI_API_KEY | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Aider | OpenAI-compatible (LiteLLM) | OpenAI 호환 | env vars | OPENAI_API_BASE | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Qwen Code | OpenAI-compatible | OpenAI 호환 | env vars | OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL | https://docs.gatellm.io/en/quickstart/openai-compatible |
| OpenHands | OpenAI-compatible (LiteLLM) | OpenAI 호환 | ~/.openhands/settings.json | base_url, model openai/ prefix | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Kimi Code CLI | OpenAI / Anthropic | OpenAI 호환 | config.toml | providers | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Plandex | OpenAI-compatible | OpenAI 호환 | custom models JSON | baseUrl | https://docs.gatellm.io/en/quickstart/openai-compatible |
| SWE-agent | OpenAI-compatible (LiteLLM) | OpenAI 호환 | env vars | OPENAI_BASE_URL | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Grok Build | OpenAI-compatible | OpenAI 호환 | config.toml | custom models | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Mistral Vibe | OpenAI-compatible | OpenAI 호환 | ~/.vibe/config.toml | providers | https://docs.gatellm.io/en/quickstart/openai-compatible |
| MiMo Code | OpenAI-compatible | OpenAI 호환 | /connect custom provider | base URL, API key | https://docs.gatellm.io/en/quickstart/openai-compatible |
| ForgeCode | OpenAI / Anthropic | OpenAI 호환 | setup wizard | base URL | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Codebuff | OpenAI-compatible | OpenAI 호환 | settings | base URL, API key | https://docs.gatellm.io/en/quickstart/openai-compatible |

### IDE 및 확장
Cline, Roo Code, Kilo Code, Continue, Zed, Cursor, Windsurf, GitHub Copilot (BYOK)
| 하네스 | 프로토콜 | 지원 | 구성 대상 | 키 이름 / 설정 | 문서 |
| --- | --- | --- | --- | --- | --- |
| Cline | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Roo Code | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Kilo Code | OpenAI-compatible | OpenAI 호환 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Continue | OpenAI-compatible | OpenAI 호환 | config.yaml | models[].apiBase | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Zed | OpenAI-compatible | OpenAI 호환 | settings.json | language_models.openai_compatible.<id>.api_url | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Cursor | OpenAI | 부분 지원 | Settings → Models → Override OpenAI Base URL | Override OpenAI Base URL | https://docs.gatellm.io/en/quickstart/openai-compatible |
| Windsurf | OpenAI-compatible | OpenAI 호환 | Settings → Models → BYOK / custom | Base URL, API Key | https://docs.gatellm.io/en/quickstart/openai-compatible |
| GitHub Copilot (BYOK) | OpenAI-compatible | OpenAI 호환 | Manage Models → OpenAI-compatible | Base URL, API Key | https://docs.gatellm.io/en/quickstart/openai-compatible |

### 관리형 플랫폼
Warp(BYOK 키 전용), Amazon Q Developer CLI, Devin — 엔드포인트가 고정되어 있거나 재정의할 수 없음
| 하네스 | 프로토콜 | 지원 | 구성 대상 | 키 이름 / 설정 | 문서 |
| --- | --- | --- | --- | --- | --- |
| Warp | OpenAI / Anthropic / Gemini (BYOK) | 부분 지원 | Settings → BYOK | BYOK API keys | https://docs.gatellm.io/en/reference/supported-models-and-sdks |
| Amazon Q Developer CLI | MCP | 사용자 정의 엔드포인트 불가 | MCP server | — | https://docs.gatellm.io/en/reference/supported-models-and-sdks |
| Devin | — | 사용자 정의 엔드포인트 불가 | — | — | https://docs.gatellm.io/en/reference/supported-models-and-sdks |

## 주의사항
### 하네스는 자체 모델 ID를 고정해 사용합니다
Claude Code는 구성된 기본값(예: claude-opus-5 또는 claude-sonnet-5)을 보냅니다 — 게이트웨이 이름이 아닙니다. 게이트웨이 모델 이름을 하네스가 요청하는 이름과 정확히 같게 지정하거나, 하네스의 모델 환경 변수(예: ANTHROPIC_MODEL)를 게이트웨이 이름으로 설정하세요. 불일치 시 첫 메시지에서 404 model_not_found가 발생합니다.

### Anthropic 프로토콜 하네스는 /v1이 아닌 루트를 사용합니다
Anthropic 스타일 클라이언트의 base URL은 게이트웨이 루트(/v1 없음)로 지정합니다 — 클라이언트가 스스로 /v1/messages를 붙이기 때문입니다. 여기에 /v1을 붙이면 경로 세그먼트가 두 번 쌓입니다.

### Codex 사용자 정의 제공자에는 wire_api="responses"가 필요합니다
Codex CLI는 사용자 정의 [model_providers.*] 블록에 wire_api = "responses"를 요구합니다. 게이트웨이는 /v1/responses를 네이티브로 구현합니다 — base_url을 여기로 지정하고 env_key를 게이트웨이 액세스 키로 설정하세요.

### LiteLLM 기반 하네스는 openai/ 모델 접두사를 원합니다
Aider, OpenHands, SWE-agent는 LiteLLM 위에 있습니다: OPENAI_API_BASE를 게이트웨이로 설정하고 모델 이름에 openai/ 접두사를 붙이세요(예: openai/gateway-model-name). 그러면 LiteLLM이 게이트웨이를 OpenAI 호환 엔드포인트로 라우팅합니다.

### 기본값은 자체 키가 아니라 구독 OAuth입니다
Codex, Gemini CLI, Qwen Code는 기본적으로 벤더의 OAuth / 구독 로그인을 사용합니다. 게이트웨이를 경유하려면 API 키 인증으로 전환해야 합니다(키와 base URL을 명시적으로 설정) — 그렇지 않으면 에이전트가 게이트웨이를 완전히 우회합니다.

### IDE는 모델 ID로 도구/비전 지원을 추론합니다
Cline / Roo / Kilo 등은 모델 이름으로 도구 호출과 비전 기능을 판단합니다. 사용자 정의 게이트웨이 이름은 함수 호출을 비활성화할 수 있습니다 — 도구 호출이 실패하면 클라이언트의 기능 탐지 규칙을 확인하거나, 알려진 계열과 일치하도록 모델 이름을 지정하세요.

### 긴 추론에는 :keep-alive와 _gateway_warning이 추가됩니다
업스트림 추론이 길어지면 게이트웨이가 SSE :keep-alive 주석 줄을 내보내며(무해합니다 — :로 시작하는 줄은 건너뛰세요), 스트림이 중간에 끊기면 오류를 내는 대신 _gateway_warning 필드를 삽입합니다. 덕분에 Claude Code 같은 하네스가 대화 전체를 중단하지 않습니다.

### Claude Code 자동 모드: 안전 판정의 응답 주체를 정하세요
자동 모드에서 Claude Code는 잠재적으로 위험한 작업 전에 서버 측 판정(요청의 safeguards 필드)을 기다립니다. 업스트림이 공식 Anthropic이면 판정이 같은 요청 안에서 생성되고 게이트웨이는 이를 그대로 전달합니다. 필드를 무시하는 제3자 업스트림이면 게이트웨이가 대신 응답하며 — 출하 기본값(allow_all)은 모든 작업을 허용하므로 호출을 그냥 두는 것보다 더 관대합니다. 해당 업스트림의 extra_config에 "anthropic_server_safeguards": "upstream"을 작성하면 경로를 업스트림으로 되돌릴 수 있습니다. 콘솔 설정은 관리자 전용입니다.

## FAQ
### Claude Code를 GateLLM을 통해 사용할 수 있나요?
예 — ANTHROPIC_BASE_URL을 게이트웨이 루트(/v1 없음)로, ANTHROPIC_API_KEY를 게이트웨이 액세스 키로 설정하세요. 게이트웨이 모델 이름을 Claude Code가 요청하는 ID(예: claude-opus-5 또는 claude-sonnet-5)와 정확히 같게 지정하거나 ANTHROPIC_MODEL로 맞추세요.
### Codex CLI를 게이트웨이로 지정하려면 어떻게 하나요?
~/.codex/config.toml에서 [model_providers.<id>] 블록을 추가하고 base_url = "https://your-gateway.gatellm.io/v1", 액세스 키 환경 변수를 가리키는 env_key, wire_api = "responses"를 설정하세요 — 게이트웨이는 /v1/responses를 네이티브로 구현합니다.
### 어떤 코딩 에이전트가 사용자 정의 엔드포인트를 쓸 수 없나요?
Devin, Amazon Q Developer CLI 같은 호스팅 플랫폼은 사용자 정의 base URL을 노출하지 않아 게이트웨이를 경유시킬 수 없습니다. Warp는 BYOK 키를 지원하지만 엔드포인트가 공식 제공자로 고정됩니다. 여기 있는 나머지는 base URL 재정의를 받습니다.
### IDE 확장(Cline / Roo / Kilo)도 동작하나요?
예 — 설정에서 "OpenAI Compatible" 제공자를 선택하고 게이트웨이 /v1 URL + 액세스 키 + 모델 이름을 붙여넣으세요. 기능 탐지에 주의하세요: 일부는 모델 ID로 도구 호출을 추론합니다.
### 모델 이름이 왜 그렇게 중요한가요?
하네스는 고정된 모델 ID를 보냅니다 — 자체 기본값이거나 구성한 이름입니다. 게이트웨이는 그 정확한 문자열로 라우팅하므로 불일치는 무시할 오타가 아니라 404 model_not_found입니다.
### LiteLLM 기반 에이전트(Aider / OpenHands / SWE-agent)는 어떤가요?
이들은 OPENAI_API_BASE를 읽고 모델 이름에 openai/ 접두사를 원합니다. 그래야 LiteLLM이 게이트웨이를 OpenAI 호환 엔드포인트로 취급합니다.

## 관련 페이지
- [홈](https://www.gatellm.io/ko/index.md)
- [요금](https://www.gatellm.io/ko/pricing.md)
- [비용 계산기](https://www.gatellm.io/ko/calculator.md)
- [소개](https://www.gatellm.io/ko/about.md)
- [데모 예약](https://www.gatellm.io/ko/demo.md)
- [FAQ](https://www.gatellm.io/ko/faq.md)
- [AI 게이트웨이 비교](https://www.gatellm.io/ko/compare.md)
- [LiteLLM 비교](https://www.gatellm.io/ko/compare/litellm.md)
- [OpenRouter 비교](https://www.gatellm.io/ko/compare/openrouter.md)
- [Alibaba Cloud AI Gateway 비교](https://www.gatellm.io/ko/compare/alibaba-cloud.md)
- [Azure API Management 비교](https://www.gatellm.io/ko/compare/azure-apim.md)
- [Apigee 비교](https://www.gatellm.io/ko/compare/apigee.md)
- [Cloudflare AI Gateway 비교](https://www.gatellm.io/ko/compare/cloudflare.md)
- [Kong AI Gateway 비교](https://www.gatellm.io/ko/compare/kong.md)
- [Portkey 비교](https://www.gatellm.io/ko/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway](https://www.gatellm.io/ko/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter](https://www.gatellm.io/ko/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey](https://www.gatellm.io/ko/compare/litellm-vs-portkey.md)
- [사용 사례](https://www.gatellm.io/ko/use-cases.md)
- [LLM 비용 절감](https://www.gatellm.io/ko/use-cases/reduce-cost.md)
- [고가용성](https://www.gatellm.io/ko/use-cases/high-availability.md)
- [멀티테넌트 격리](https://www.gatellm.io/ko/use-cases/multi-tenant.md)
- [컴플라이언스 및 감사](https://www.gatellm.io/ko/use-cases/compliance-audit.md)
- [증상별 트러블슈팅](https://www.gatellm.io/ko/use-cases/troubleshooting.md)
- [다중 벤더 혼합 모델 스택](https://www.gatellm.io/ko/use-cases/mixed-model-stack.md)
- [Office 내 AI 셀프 호스팅](https://www.gatellm.io/ko/use-cases/self-hosted-office-ai.md)
- [Token 사용량 가시성 및 귀속](https://www.gatellm.io/ko/use-cases/token-ops.md)
- [Token FinOps: AI 비용 배분 및 통제](https://www.gatellm.io/ko/use-cases/token-finops.md)
- [MCP 도구 거버넌스](https://www.gatellm.io/ko/use-cases/mcp-tool-governance.md)
- [모든 모델에 웹 검색 추가](https://www.gatellm.io/ko/use-cases/web-search-grounding.md)
- [다중 키 로테이션 및 대기](https://www.gatellm.io/ko/use-cases/multi-key-pooling.md)
- [연결 클라이언트 접근 제어](https://www.gatellm.io/ko/use-cases/client-admission-control.md)
- [모델 사용 정책 강제](https://www.gatellm.io/ko/use-cases/enforce-model-policy.md)
- [클라이언트에 모델 선택 비노출](https://www.gatellm.io/ko/use-cases/automatic-model-tiering.md)
- [하나의 프로토콜, 어떤 모델이든](https://www.gatellm.io/ko/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 추가 기능](https://www.gatellm.io/ko/office-addin.md)
- [용어집](https://www.gatellm.io/ko/glossary.md)
- [모델 카탈로그](https://www.gatellm.io/ko/models.md)
- [SDK 및 프레임워크 통합](https://www.gatellm.io/ko/integrations.md)
- [보안 및 컴플라이언스](https://www.gatellm.io/ko/security.md)