3가지 코딩 CLI를 위한 통합 게이트웨이 설정 및 문제 해결 가이드 (2026): Gemini CLI, Codex CLI, Claude Code

코딩 CLI를 매일 사용하는 개발자에게 설정 과정의 마찰은 곧 비용입니다. 여러 개의 API 키, 서로 다른 설정 형식, 인증 충돌, 그리고 401/429/스트림 중단과 같은 고질적인 문제들이 발생하곤 합니다.

가장 빠른 경로를 원하시나요? 아래의 전용 통합 가이드를 이용하세요 (권장):

• Claude CLI / Claude Code
• Codex CLI
• Gemini CLI

여기서 시작하세요 (가장 빠른 설정)

원하는 도구를 선택하고 위의 도입부에 링크된 전용 가이드를 따르세요.

핵심 요약: 5분 체크리스트 (도구 선택)

참고: 일부 CLI는 엔드포인트 형태가 약간 다를 수 있습니다(예: /v1 또는 끝에 슬래시 포함). 각 도구별 가이드를 따라 해당 CLI가 기대하는 정확한 형식을 확인하세요.

코딩 CLI를 왜 게이트웨이 호스트를 통해 라우팅해야 할까요?

다음 중 하나 이상이 필요한 경우 게이트웨이/라우터를 사용하세요.

1. 여러 도구에서 키 관리의 번거로움 해결
2. 도구 설정을 다시 작성하지 않고 모델/제공업체 전환
3. 운영 제어(재시도/타임아웃/감사)를 위해 트래픽을 한곳으로 통합
4. 도구 및 제공업체의 변화에도 워크플로우 안정성 유지

이 가이드는 설정 과정과 운영상 발생하는 문제, 즉 "어떤 것이 고장 나고 어떻게 고치는지"에 초점을 맞춥니다.

결정 포인트: 제공업체 직접 연결 vs 통합 게이트웨이 호스트

선택하기 전에 프로덕션 환경에서의 실제 트레이드오프를 확인하세요.

경로 A — Codex CLI (config.toml을 통한 맞춤형 제공업체)

최소 단계

1. 설치:

   npm install -g @openai/codex

2. API 키 설정:

   export OPENAI_API_KEY="YOUR_EVOLINK_KEY"

3. 설정 파일 ~/.codex/config.toml 생성/수정

4. 확인:

   codex "Who are you"

최소 config.toml 스니펫 (예시)

model = "gpt-5.2"
model_provider = "evolink"

[model_providers.evolink]
name = "EvoLink API"
base_url = "https://api.evolink.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

경로 B — Claude Code / Claude CLI (settings.json + Anthropic 베이스 URL)

최소 단계

1. 설치:

   npm install -g @anthropic-ai/claude-code

2. ~/.claude/settings.json 수정

3. 확인:

   claude "Who are you"

최소 settings.json 스니펫 (예시)

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_EVOLINK_KEY",
    "ANTHROPIC_BASE_URL": "https://api.evolink.ai",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": { "allow": [], "deny": [] }
}

인증 충돌 주의 (공통 함정)

기존에 구독 플로우를 통해 로그인한 상태에서 API 키/토큰을 따로 설정하면 동작이 불안정할 수 있습니다. 경고가 뜨거나 예상치 못한 인증 동작이 발생하는 경우:

• claude /logout 명령어로 기존 인증을 제거하거나,
• 충돌하는 Anthropic 환경 변수를 해제(unset)한 후 터미널을 재시작하세요.

경로 C — Gemini CLI (.env + 맞춤형 베이스 URL)

필수 조건

확인 방법:

node -v

최소 단계

1. 설치:

   npm install -g @google/gemini-cli

2. ~/.gemini/.env 생성/수정

3. 확인:

   gemini "Who are you"

최소 .env 스니펫 (예시)

GOOGLE_GEMINI_BASE_URL="https://api.evolink.ai/"
GEMINI_API_KEY="YOUR_EVOLINK_KEY"
GEMINI_MODEL="gemini-2.5-pro"

알려진 함정: 베이스 URL이 적용되지 않음

• 터미널 세션을 재시작하세요.
• .env 파일 경로가 올바른지 확인하세요.
• CLI 인증 모드와 캐시된 세션을 확인하세요.
• 설정 문제인지 실행 시점의 문제인지 확인하기 위해 아주 짧은 프롬프트로 다시 테스트해보세요.

설정 변경이 적용되지 않는 이유 (우선순위 체크리스트)

"변경되지 않음" 문제는 대부분 다음 중 하나에서 발생합니다.

1. 잘못된 파일 위치 — Codex: ~/.codex/config.toml / Claude: ~/.claude/settings.json / Gemini: ~/.gemini/.env
2. 파일 수정 후 재시작하지 않음 — 터미널이나 CLI 프로세스를 재시작하세요.
3. 환경 변수가 설정 파일을 덮어씀 — 특히 Claude 인증 충돌(토큰 vs 로그인)에서 자주 발생합니다.

빠른 확인:

env | grep -E "OPENAI_API_KEY|ANTHROPIC_|GEMINI_|GOOGLE_GEMINI_BASE_URL"

문제 해결 요약표 (401/403/429/스트리밍/도구 호출/타임아웃)

401 / 403 (인증 오류)

• 도구가 읽는 변수에 키가 제대로 설정되어 있나요?
  • Codex: OPENAI_API_KEY
  • Claude: ANTHROPIC_AUTH_TOKEN
  • Gemini: GEMINI_API_KEY
• 베이스 URL이 통합 가이드에서 사용하는 엔드포인트 형식과 일치하나요?

• 환경 변수를 다시 export하고 shell을 재시작하세요.
• 설정 파일 위치와 철자를 다시 확인하세요.
• Claude의 경우: /logout 후 깨끗하게 다시 인증하세요.

401/403 해결을 위해 새 키가 필요하신가요? API 키 생성/관리 →

429 (속도 제한 / 쿼타 부족 / 스로틀링)

• 동시성 줄이기 (많은 병렬 실행 피하기)
• 대규모 작업 사이에 짧은 지연 시간 추가
• 지수 백오프(exponential backoff)로 재시도 (게이트웨이에서 자동 처리 가능 시 활용)

429가 지속되면 이를 운영상의 문제(갑작스러운 트래픽 분출, 긴 스트리밍 세션 또는 과도한 도구 호출)로 간주하고 대처해야 합니다.

스트림 중단 / 출력 지연

• 짧은 프롬프트로 연결성을 확인하세요.
• 네트워크 문제 격리를 위해 VPN/프록시를 일시적으로 비활성화해보세요.
• 깨끗한 디렉토리에서 다시 실행해보세요 (너무 큰 저장소 컨텍스트 피하기).

도구 호출 실패 (에이전트가 명령/파일 실행 못 함)

• 권한 정책이 실행을 차단함
• 도구 환경에 의존성(git, ripgrep, 빌드 도구 등)이 누락됨
• 경로/샌드박스 제한

• 도구 권한 정책과 작업 디렉토리를 확인하세요.
• 최소한의 도구 동작으로 재현해 보세요.

타임아웃 (시간 초과)

• 작업을 더 작은 프롬프트로 나누세요.
• 저장소 컨텍스트 크기를 줄이세요.
• 첫 테스트에서 너무 긴 스트리밍 세션은 피하세요.

모델 전환 (빠른 방법)

• Codex CLI: ~/.codex/config.toml에서 model = "..." 업데이트
• Claude Code: /model 명령어 사용 (지원되는 버전의 경우)
• Gemini CLI: /model 명령어 사용 또는 .env에서 GEMINI_MODEL 업데이트

다음 단계

여러 코딩 CLI를 사용하는 경우, 마찰을 줄이는 가장 빠른 방법은 다음을 표준화하는 것입니다.

• 단일 게이트웨이 호스트 사용
• 도구별 예측 가능한 설정 템플릿 사용
• 반복 가능한 문제 해결 플레이북 유지

도입부의 전용 통합 가이드부터 시작해 보세요.

자주 묻는 질문 (FAQ)

코딩 CLI의 "맞춤형 LLM 엔드포인트"란 무엇인가요?

CLI가 기본 제공업체 엔드포인트 대신 요청을 보내는 베이스 URL입니다. 실질적으로는 단일 호스트 뒤에 하나 이상의 모델 API를 노출하는 게이트웨이/라우터 역할을 합니다.

도구마다 엔드포인트 형식(/v1, 끝 슬래시 등)이 왜 다른가요?

Codex CLI 설정 파일은 어디에 있나요?

Codex CLI에서 맞춤형 base_url을 설정하려면 어떻게 하나요?

Codex 설정에서 wire_api = "responses"는 무엇을 의미하나요?

CLI가 엔드포인트와 통신할 때 사용하는 API 형태를 나타냅니다. 통합 가이드의 값과 일치하도록 유지하세요.

Claude Code의 settings.json은 어디에 있나요?

ANTHROPIC_BASE_URL은 무엇에 사용되나요?

Claude Code가 요청을 보낼 베이스 URL을 설정하여, 기본 제공업체가 아닌 맞춤형 엔드포인트로 라우팅할 수 있게 합니다.

Claude Code에서 인증 충돌 경고가 뜨는 이유는 무엇인가요?

Gemini CLI는 .env를 어디서 읽어오나요?

GOOGLE_GEMINI_BASE_URL이 적용되지 않는 이유는 무엇인가요?

Gemini CLI에 적합한 Node.js 버전은 무엇인가요?

Node.js 20 이상의 버전을 사용하세요.

맞춤형 엔드포인트 사용 시 401/403 오류를 빠르게 해결하려면 어떻게 하나요?

올바른 키 변수가 설정되었는지 확인하고, 엔드포인트 형식을 점검한 뒤 터미널을 재시작하세요. Claude의 경우 로그아웃이나 변수 해제로 인증 충돌을 제거했는지 확인하세요.

코딩 CLI에서의 429 오류는 무엇을 의미하나요?

보통 속도 제한(Rate limit)이나 할당량(Quota) 초과를 의미합니다. 동시 실행을 줄이고, 요청 사이에 지연 시간을 두며, 지수 백오프로 재시도해 보세요.

CLI가 스트리밍 출력 도중 멈춥니다—가장 먼저 무엇을 시도해야 하나요?

짧은 프롬프트로 테스트하고, 일시적으로 VPN/프록시를 끈 뒤 저장소 컨텍스트 크기를 줄여보세요. 큰 작업은 작은 프롬프트 여러 개로 나누는 것이 좋습니다.