Claude Code와 Codex를 HiAPI에 연결: 하나의 Key로 작업별 모델 선택

최근 카파시가 연초에 했던 한마디가 다시 회자되며 화제가 되었습니다: the new default is that you are not writing the code directly 99% of the time, you are orchestrating agents who do and acting as oversight. 번역하면, 새로운 기본값은 99%의 시간 동안 더 이상 직접 코드를 작성하지 않고, 대신 작업을 수행하는 agent를 편성(orchestrate)하며 자신은 감독만 하는 것입니다. 이 말은 그가 agentic engineering 개념을 제시했을 때의 게시물에서 나온 것으로, No Priors 팟캐스트에서도 한마디 덧붙였습니다: I don't think I've typed a line of code probably since December.

화제가 되는 것과 별개로, 데이터는 이것이 구호가 아님을 더 잘 보여줍니다. Claude Code의 연환산 운영 수익은 이미 $2.5B를 넘었고(2026년 2월 Series G 공식 발표 기준, 감사받지 않은 ARR), GitHub Copilot은当年 $1B에 도달하는 데 약 3년이 걸렸습니다. JetBrains 2026 개발자 생태계 조사(1.5만 명 이상 응답)에 따르면, 약 90%의 전문 개발자가 매주 AI 프로그래밍 agent를 사용하며, Claude Code의 업무 환경 채택률은 18%에서 39%로(미국 47%), Codex는 3%에서 16%로 상승했습니다.

문제도 뒤따랐습니다: agent는 늘어났지만 설정과 청구는 여전히 각자 관리합니다. 많은 사람이 Claude Code와 Codex를 동시에 사용하지만, 두 도구는 각자 key를 신청하고 각자 충전하며 각자 사용량을 확인하고, 모델을 바꾸려면 다시 신청 절차를 거쳐야 합니다. 이 글은 하나의 HiAPI Key로 두 도구를 모두 연결하는 방법, 그리고 연결 후 모델을 어떻게 선택하고 전환하는지 설명합니다.

먼저 결론

• 하나의 Key로 두 도구 관리: HiAPI의 API Key를 Claude Code와 Codex에 동시에 사용하며, 잔액·사용량·청구가 모두 하나의 백엔드에 있습니다
• 각자 가장 강력한 모델 사용: Claude Code는 Anthropic Messages 프로토콜(/v1/messages)로 HiAPI의 Claude 모델을, Codex는 Responses API(/v1/responses)로 GPT-6.1 계열 모델을 사용합니다
• 두 가지 레드라인 내에서의 자유: Claude Code는 공식적으로 어떤 게이트웨이를 통해서든 비-Claude 모델로 라우팅하는 것을 지원하지 않으므로, 올바른 방식은 두 도구가 각자 모델 패밀리에 연결하는 것이지 하나의 도구로 모두 커버하는 것이 아닙니다
• 최단 5분 연결: /connect/agents 페이지에서 도구 + 모델 + 운영체제를 선택하고 생성된 설정을 복사하세요. Claude Code와 Codex는 CC Switch 원클릭 가져오기를 지원합니다
• 모델 교체는 한 곳만 수정: Claude Code는 settings.json의 모델 필드를, Codex는 hiapi.config.toml의 model 한 줄을 수정하면 되며 Key는 바꿀 필요가 없습니다

HiAPI의 해법: 하나의 Key, 두 도구

HiAPI는 여러 모델 패밀리를 집계하는 API 플랫폼으로, 외부에 몇 가지 표준 프로토콜을 통일적으로 노출합니다. 프로그래밍 agent 쪽으로는 공식적으로 4개 도구의 원클릭 연결 페이지를 제공합니다: /zh/connect/agents(영문판 /en/connect/agents)로, Claude Code, Codex CLI, OpenCode, Hermes Agent를 지원합니다.

프로토콜 매핑이 올바른 연결의 핵심입니다:

도구	프로토콜	인터페이스 경로	HiAPI 측 선택 가능 모델
Claude Code	Anthropic Messages	/v1/messages	claude-opus-5-5, claude-sonnet-4-6, claude-opus-4-8, claude-opus-4-8@aws (총 4개)
Codex CLI	Responses API	/v1/responses	gpt-6.1-sol, gpt-6.1-terra, gpt-6-astra, gpt-5.6 계열, deepseek-v4 계열 (총 9개)
OpenCode / Hermes Agent	Chat Completions	/v1/chat/completions	각 패밀리 텍스트 모델, 커버리지 가장 넓음

즉, Claude Code의 강점은 장기 코딩 agent 작업에 있으므로 Claude 패밀리의 플래그십을 배치하고, Codex의 강점은 대량 실행에 있으므로 GPT-6.1 계열을 배치합니다. 하나의 Key로 양쪽 모두 인증할 수 있고 청구가 합쳐집니다.

반드시 명확히 해야 할 한마디: Anthropic은 공식적으로 Claude Code를 어떤 게이트웨이를 통해서든 비-Claude 모델로 라우팅하는 것을 명확히 지원하지 않습니다. GPT 모델을 Claude Code에 억지로 넣으면 도구 호출과 agent 동작이 불안정해지고, 문제가 생겨도 공식적인 보증이 없습니다. 따라서 "하나의 Key로 언제든 모델 전환"의 정확한 의미는 두 도구 사이에서 작업에 따라 분배하고, 각 도구는 자신에게 가장 강력한 모델을 사용한다는 것이지, 하나의 도구 안에서 패밀리를 혼용하는 것이 아닙니다.

Claude Code 하나만 사용한다면, 이전에 작성한 단일 도구 설정 가이드 《HiAPI로 Claude Code 연결: 월 $100 구독료를 절약하는 완전한 설정 가이드》를 참고하세요. 이 글은 두 도구가 하나의 Key를 공유하는 방법과 전환 전략에 중점을 둡니다.

연결 방법 1(권장): /connect/agents 페이지에서 설정 생성

가장 간편한 연결 방법으로, 전 과정 클릭 선택만 하면 되고 설정을 직접 작성할 필요가 없습니다:

1. hiapi.ai/zh/connect/agents를 열고 「HiAPI를 Agent에 연결」을 클릭합니다
2. 도구 선택: Claude Code 또는 Codex CLI
3. 모델 선택: 예를 들어 Claude Code 측은 claude-opus-5-5, Codex 측은 gpt-6.1-sol
4. 운영체제 선택: macOS / Windows / Linux, 설정의 경로가 그에 맞게 바뀝니다
5. 생성된 설정을 복사하여 안내에 따라 해당 파일에 붙여넣으면 됩니다

Claude Code와 Codex는 CC Switch 원클릭 가져오기를 지원합니다: HiAPI의 API Keys 페이지에서 가져오기를 클릭하면 브라우저가 CC Switch를 실행하여 설정 쓰기를 완료합니다. 가져오기 링크 자체에는 키가 포함되지 않으며, Key는 로컬 환경 변수에 저장되므로 안심하셔도 됩니다.

버전 요구 사항을 먼저 확인하세요: Codex CLI는 0.134 이상이 필요하며 codex --version으로 확인하고, Claude Code는 claude --version으로 버전 번호가 정상 출력되는지 확인하세요.

연결 방법 2: 설정 파일 직접 작성

수동 설정도 복잡하지 않으며, 두 파일이 각각 하나의 도구를 담당합니다.

Claude Code: ~/.claude/settings.json

~/.claude/settings.json(Windows는 %USERPROFILE%\.claude\settings.json)의 env 블록에 작성합니다:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.hiapi.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的 HiAPI API Key",
    "ANTHROPIC_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-6",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

필드별 설명:

• ANTHROPIC_BASE_URL은 https://api.hiapi.ai를 가리키며, /v1을 붙이지 않습니다. 클라이언트가 스스로 /v1/messages를 조합합니다
• ANTHROPIC_AUTH_TOKEN에 HiAPI API Key를 입력하며, Bearer 인증을 사용합니다
• ANTHROPIC_MODEL과 OPUS / SONNET 두 별칭 모두 HiAPI에서 선택한 모델을 가리킵니다(HiAPI는 공식 Claude 모델 ID를 서비스하지 않으며, 별칭이 통일적으로 가리킵니다)
• ANTHROPIC_DEFAULT_HAIKU_MODEL은 claude-sonnet-4-6으로 고정되며, Claude Code가 백그라운드 잡무(컨텍스트 압축, 커밋 메시지 생성 등)를 처리하는 슬롯입니다
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1은 새 텍스트 파이프라인이 experimental beta 요청 필드를 거부하기 때문이며, 꺼두면 문제를 피할 수 있습니다

Codex: ~/.codex/hiapi.config.toml

~/.codex/hiapi.config.toml(Windows는 %USERPROFILE%\.codex\hiapi.config.toml)을 새로 만듭니다:

model_provider = "hiapi"
model = "gpt-6.1-sol"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
wire_api = "responses"

그런 다음 shell에서 환경 변수를 설정하고 실행합니다:

export HIAPI_API_KEY="你的 HiAPI API Key"
codex --profile hiapi

Windows PowerShell에서는 $env:HIAPI_API_KEY = "..."에 해당합니다. 여기서 base_url은 /v1이 붙는다는 점이 Claude Code 쪽과 다르니 양쪽을 그대로 복사해 혼용하지 마세요. wire_api = "responses"는 Responses 프로토콜을 사용함을 선언하며, 이는 Codex의 필수 요구 사항입니다.

모델 선택 방법: 복잡한 작업은 Opus, 대량 실행은 GPT-6.1

두 도구를 모두 연결한 후에는 모델 선택이 작업별 라우팅 문제가 됩니다. 권장 사항은 매우 직접적입니다:

• 고난도·장기 작업에는 claude-opus-5-5: 파일 간 리팩터링, 장시간 디버깅, 전체 코드베이스를 이해해야 하는 작업. Claude Code 측의 플래그십이며 컨텍스트 윈도우가 1M에 달합니다
• 일상적인 고빈도 대량 실행에는 gpt-6.1-sol / gpt-6.1-terra: 배치 재작성, 단일 파일 기능, 스크립트 생성 등 작업량이 많고 단일 작업이 복잡하지 않은 경우, 한 단계 저렴한 모델을 사용하면 청구 차이가 확연합니다
• gpt-6-astra는 품질에 더 민감한 Responses 시나리오에: 가격이 한 단계 높으므로 필요에 따라 활성화하세요

주요 모델의 플랫폼 가격($/M token, 2026-10 기준, 기본 등급):

모델	입력	출력	캐시 읽기	컨텍스트
claude-opus-5-5	$2.02	$10.08	$0.10	1M
claude-sonnet-4-6	$3.00	$15.00	$0.30	—
gpt-6.1-sol	$0.50	$2.50	$0.025	1.05M
gpt-6.1-terra	$0.25	$1.25	$0.0125	1.05M
gpt-6-astra	$2.50	$12.50	$0.25	1.05M(272K 초과 시 장문 할증 등급 적용)

캐시 읽기 가격 열을 주목하세요: agent 세션에서 많은 token이 캐시 적중에서 나오며, gpt-6.1-terra의 캐시 읽기는 $0.0125/M에 불과하므로 긴 세션에서 같은 저장소를 반복 수정할 때 실제 청구가 입력 가격으로 추산한 것보다 상당히 낮습니다. 대량 실행과 비용 절감은 양자택일이 아닙니다.

Opus 5.5와 GPT-6.1 Sol의 능력 지향을 더 깊이 비교하려면 《Claude Opus 5.5 대 GPT-6.1 Sol 비교》를, Terra의 최근 인하 폭과 배경은 《GPT-6.1 Terra 인하 분석》에 전체 분석이 있습니다. 두 모델의 실시간 가격과 파라미터는 모델 상세 페이지를 기준으로 하세요.

모델 전환이 얼마나 쉬운가

이것이 이 방안에서 가장 과소평가된 장점입니다. 모델 교체에는 두 가지 동작만 있습니다:

• Claude Code: ~/.claude/settings.json의 ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL 세 곳의 값을 수정합니다(HiAPI에서 opus/sonnet 별칭이 모두 가리키므로 동일한 새 모델 ID로 바꾸면 됩니다). 세션을 다시 열면 적용됩니다
• Codex: ~/.codex/hiapi.config.toml의 model = "..." 한 줄을 수정하면 다음 codex --profile hiapi 실행 시 적용됩니다

Key는 처음부터 끝까지 바꿀 필요가 없습니다. "각 도구에 공식 key를 별도로 신청"하는 예전 방식과 비교하면: 모델을 바꿀 때 재신청, 승인 대기, 키 관리 수정이 필요했지만 이제는 한 줄 설정의 문제입니다. CC Switch 가져오기를 사용했다면 /connect/agents 페이지에서 모델을 다시 선택하고 가져오기를 다시 클릭해도 되며, 전 과정 그래픽 조작입니다.

더 많은 모델을 연결하고 싶다면 OpenCode와 Hermes Agent는 Chat Completions 프로토콜을 사용하며 선택 가능한 모델 커버리지가 가장 넓고, 동일한 페이지 흐름입니다. 멀티모달과 월드 모델类의 새 모델에 관심이 있다면 《Genie 4 월드 모델 실측》도 참고하세요.

자주 묻는 질문

Claude Code에서 HiAPI를 통해 GPT 모델을 사용할 수 있나요?

불가능하며, 필요도 없습니다. Anthropic은 공식적으로 Claude Code를 어떤 게이트웨이를 통해서든 비-Claude 모델로 라우팅하는 것을 지원하지 않으며, 억지로 연결하면 도구 호출과 agent 동작이 불안정해지고 공식 보증도 없습니다. HiAPI에서 Claude Code의 선택 가능 모델은 claude-opus-5-5, claude-sonnet-4-6, claude-opus-4-8, claude-opus-4-8@aws 이 4개입니다. GPT-6.1 계열 모델을 사용하려면 Codex 측으로 가면 Responses 프로토콜이 기본 지원합니다.

하나의 HiAPI Key를 Claude Code와 Codex에 동시에 사용할 수 있나요?

가능하며, 이것이 이 방안의 핵심입니다. 두 도구는 동일한 Key를 공유하며 인증 방식은 다르지만(Claude Code는 ANTHROPIC_AUTH_TOKEN, Codex는 HIAPI_API_KEY 환경 변수) 모두 같은 Key입니다. 잔액, 사용량, 청구는 같은 백엔드에서 확인하며 도구별로 그룹화하여 통계를 냅니다.

CC Switch 원클릭 가져오기는 안전한가요?

안전합니다. 가져오기 링크 자체에는 키가 포함되지 않으며, Key는 로컬 환경 변수에 저장됩니다. 흐름은: HiAPI에서 Key를 생성한 후 API Keys 페이지에서 CC Switch 가져오기를 클릭하면 브라우저가 CC Switch를 실행하여 설정을 씁니다. 그래픽 흐름이 불안하다면 settings.json과 hiapi.config.toml을 직접 작성해도 완전히 동등합니다.

두 도구를 모두 설정했는데 연결되었는지 어떻게 확인하나요?

Claude Code 측은 claude --version을 실행하여 클라이언트가 정상인지 확인한 후 아무 세션이나 열어 한마디 보내고 HiAPI 백엔드에서 사용량이 증가했는지 확인합니다. Codex 측은 CLI 0.134+가 필요하며, codex --profile hiapi로 시작한 후 마찬가지로 작업을 하나 보내 백엔드 계량을 확인합니다. 처음에는 각각 작은 작업을 하나씩 실행하여 과금과 모델 ID가 모두 맞는지 확인한 후 본격적으로 사용하는 것을 권장합니다.

OpenCode와 Hermes Agent는 연결할 가치가 있나요?

팀 관습에 따라 다릅니다. 이 두 도구는 Chat Completions 프로토콜을 사용하며 선택 가능한 모델 패밀리가 가장 많아, 하나의 클라이언트에서 여러 모델 패밀리를 넘나들어야 하는 시나리오에 적합합니다. 설정 흐름은 Claude Code / Codex와 완전히 동일하며, 역시 /connect/agents 페이지입니다.

모델을 바꾸면 진행 중인 세션에 영향이 있나요?

수정하는 것은 새 세션에 적용되는 설정입니다. 이미 열려 있는 세션은 시작 시 읽은 모델을 사용하므로, 설정을 바꾼 후 세션을 다시 열면 되며 기존 세션 기록에는 영향이 없습니다.

핵심 결론

카파시의 99%라는 말이 다시 회자된다는 것은 agentic engineering이 더 이상前沿 플레이어의 게임이 아니라 기본 작업 방식임을 보여줍니다. 기본 작업 방식에서 Claude Code와 Codex를 동시에 사용하는 사람은 점점 늘어날 것이고, 설정과 청구의 파편화는 실제 마찰입니다. HiAPI의 방안은 하나의 Key로 두 도구를 연결하는 것입니다: Claude Code는 Messages 프로토콜로 Claude 패밀리의 플래그십을, Codex는 Responses 프로토콜로 GPT-6.1 계열을 사용하여 각자 가장 강력한 모델을 쓰고 청구가 합쳐집니다. 연결은 /connect/agents 페이지에서 설정 생성 + CC Switch 가져오기로 5분이면 작동하며, 모델 전환은 설정 한 줄만 바꾸면 되고 Key는 그대로입니다. 작업별 라우팅(어려운 문제는 Opus 5.5, 대량 실행은 GPT-6.1 Sol/Terra)이 현재 품질과 청구를 동시에 잡는 최적해입니다.