Blog

Claude Code와 gpt-oss 활용법

Ashley Goolam

Ashley Goolam

8 August 2025

Claude Code와 gpt-oss 활용법

Claude Code 내에서 Open AI의 오픈 웨이트 모델인 GPT-OSS로 코딩 워크플로우를 강화하고 싶으신가요? 정말 좋은 소식입니다! 2025년 8월에 출시된 GPT-OSS(20B 또는 120B 변형)는 코딩 및 추론을 위한 강력한 도구이며, Claude Code의 세련된 CLI 인터페이스와 무료 또는 저렴한 비용으로 페어링할 수 있습니다. 이 대화형 가이드에서는 Hugging Face, OpenRouter 또는 LiteLLM을 사용하여 GPT-OSS를 Claude Code와 통합하는 세 가지 방법을 안내해 드립니다. 지금 바로 시작하여 AI 코딩 도우미를 가동해 보세요!

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

최대 생산성으로 개발팀이 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 귀하의 모든 요구 사항을 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
버튼

GPT-OSS란 무엇이며 Claude Code와 함께 사용해야 하는 이유는 무엇인가요?

GPT-OSS는 Open AI의 오픈 웨이트 모델 제품군으로, 20B 및 120B 변형은 코딩, 추론 및 에이전트 작업에 탁월한 성능을 제공합니다. 128K 토큰 컨텍스트 창과 Apache 2.0 라이선스를 통해 유연성과 제어를 원하는 개발자에게 완벽합니다. Anthropic의 CLI 도구(버전 0.5.3+)인 Claude Code는 대화형 코딩 기능으로 개발자들에게 인기가 많습니다. OpenAI 호환 API를 통해 Claude Code를 GPT-OSS로 라우팅하면 Anthropic 구독 비용 없이 Claude의 익숙한 인터페이스를 즐기면서 GPT-OSS의 오픈 소스 기능을 활용할 수 있습니다. 준비되셨나요? 설정 옵션을 살펴보겠습니다!

Open AI의 오픈 웨이트 모델

Claude Code와 GPT-OSS 사용을 위한 전제 조건

시작하기 전에 다음을 확인하세요:

클로드 코드

경로 A: Hugging Face에서 GPT-OSS 자체 호스팅

완전한 제어를 원하시나요? Hugging Face의 추론 엔드포인트에 GPT-OSS를 호스팅하여 비공개적이고 확장 가능한 설정을 구축하세요. 방법은 다음과 같습니다:

1단계: 모델 가져오기

  1. Hugging Face의 GPT-OSS 저장소(openai/gpt-oss-20b 또는 openai/gpt-oss-120b)를 방문하세요.
  2. 모델에 액세스하려면 Apache 2.0 라이선스에 동의하세요.
  3. 또는 코딩 중심 모델로 Qwen3-Coder-480B-A35B-Instruct(Qwen/Qwen3-Coder-480B-A35B-Instruct)를 사용해 보세요 (가벼운 하드웨어에는 GGUF 버전을 사용하세요).
Hugging Face GPT-OSS 모델

2단계: 텍스트 생성 추론 엔드포인트 배포

  1. 모델 페이지에서 Deploy > Inference Endpoint를 클릭하세요.
  2. Text Generation Inference (TGI) 템플릿(≥ v1.4.0)을 선택하세요.
  3. Enable OpenAI compatibility를 선택하거나 고급 설정에서 --enable-openai를 추가하여 OpenAI 호환성을 활성화하세요.
  4. 하드웨어 선택: 20B의 경우 A10G 또는 CPU, 120B의 경우 A100. 엔드포인트를 생성하세요.

3단계: 자격 증명 수집

  1. 엔드포인트 상태가 실행 중이 되면 다음을 복사하세요:

2. 모델 ID를 기록해 두세요 (예: gpt-oss-20b 또는 gpt-oss-120b).

4단계: Claude Code 구성

  1. 터미널에서 환경 변수를 설정하세요:
export ANTHROPIC_BASE_URL="https://<your-endpoint>.us-east-1.aws.endpoints.huggingface.cloud"
export ANTHROPIC_AUTH_TOKEN="hf_xxxxxxxxxxxxxxxxx"
export ANTHROPIC_MODEL="gpt-oss-20b"  # 또는 gpt-oss-120b

<your-endpoint> 및 hf_xxxxxxxxxxxxxxxxx를 실제 값으로 바꾸세요.

2. 설정을 테스트하세요:

claude --model gpt-oss-20b

Claude Code는 TGI의 /v1/chat/completions API를 통해 응답을 스트리밍하여 OpenAI의 스키마를 모방하며, GPT-OSS 엔드포인트로 라우팅됩니다.

5단계: 비용 및 확장 참고 사항

docker run --name tgi -p 8080:80 -e HF_TOKEN=hf_xxxxxxxxxxxxxxxxx ghcr.io/huggingface/text-generation-inference:latest --model-id openai/gpt-oss-20b --enable-openai

그런 다음 ANTHROPIC_BASE_URL="http://localhost:8080"로 설정하세요.

경로 B: OpenRouter를 통한 GPT-OSS 프록시

DevOps가 없으신가요? 문제없습니다! OpenRouter를 사용하여 최소한의 설정으로 GPT-OSS에 액세스하세요. 빠르고 청구를 처리해 줍니다.

1단계: 등록 및 모델 선택

  1. openrouter.ai에서 가입하고 Keys 섹션에서 API 키를 복사하세요.
  2. 모델 슬러그를 선택하세요:
OpenRouter의 GPT-OSS 모델

2단계: Claude Code 구성

  1. 환경 변수를 설정하세요:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_AUTH_TOKEN="or_xxxxxxxxx"
export ANTHROPIC_MODEL="openai/gpt-oss-20b"

or_xxxxxxxxx를 OpenRouter API 키로 바꾸세요.

2. 테스트하세요:

claude --model openai/gpt-oss-20b

Claude Code는 OpenRouter의 통합 API를 통해 GPT-OSS에 연결되며, 스트리밍 및 폴백을 지원합니다.

3단계: 비용 참고 사항

경로 C: 혼합 모델 플릿에 LiteLLM 사용

단일 워크플로우에서 GPT-OSS, Qwen 및 Anthropic 모델을 저글링하고 싶으신가요? LiteLLM은 모델을 원활하게 핫스왑하는 프록시 역할을 합니다.

1단계: LiteLLM 설치 및 구성

  1. LiteLLM 설치:
pip install litellm

2. 구성 파일(litellm.yaml) 생성:

model_list:
  - model_name: gpt-oss-20b
    litellm_params:
      model: openai/gpt-oss-20b
      api_key: or_xxxxxxxxx  # OpenRouter 키
      api_base: https://openrouter.ai/api/v1
  - model_name: qwen3-coder
    litellm_params:
      model: openrouter/qwen/qwen3-coder
      api_key: or_xxxxxxxxx
      api_base: https://openrouter.ai/api/v1

or_xxxxxxxxx를 OpenRouter 키로 바꾸세요.

3. 프록시 시작:

litellm --config litellm.yaml

2단계: Claude Code를 LiteLLM으로 지정

  1. 환경 변수를 설정하세요:
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="litellm_master"
export ANTHROPIC_MODEL="gpt-oss-20b"

2. 테스트하세요:

claude --model gpt-oss-20b

LiteLLM은 OpenRouter를 통해 GPT-OSS로 요청을 라우팅하며, 비용 로깅 및 안정성을 위한 간단한 셔플 라우팅을 제공합니다.

3단계: 참고 사항

LiteLLM이 처음이신가요? 여기를 클릭하여 자세히 알아보세요.

Claude Code로 GPT-OSS 테스트하기

GPT-OSS가 작동하는지 확인해 봅시다! Claude Code를 열고 다음 명령을 시도해 보세요:

코드 생성:

claude --model gpt-oss-20b "Write a Python REST API with Flask"

다음과 같은 응답을 예상할 수 있습니다:

from flask import Flask, jsonify
app = Flask(__name__)
@app.route('/api', methods=['GET'])
def get_data():
    return jsonify({"message": "Hello from GPT-OSS!"})
if __name__ == '__main__':
    app.run(debug=True)

코드베이스 분석:

claude --model gpt-oss-20b "Summarize src/server.js"

GPT-OSS는 128K 컨텍스트 창을 활용하여 JavaScript 파일을 분석하고 요약을 반환합니다.

디버깅:

claude --model gpt-oss-20b "Debug this buggy Python code: [paste code]"

87.3%의 HumanEval 통과율로 GPT-OSS는 문제를 정확하게 찾아내고 수정할 수 있습니다.

문제 해결 팁

Claude Code와 함께 GPT-OSS를 사용해야 하는 이유

GPT-OSS와 Claude Code를 페어링하는 것은 개발자의 꿈입니다. 다음을 얻을 수 있습니다:

사용자들은 GPT-OSS의 코딩 능력에 대해 극찬하며, "다중 파일 프로젝트를 위한 예산 친화적인 괴물"이라고 부릅니다. 자체 호스팅하든 OpenRouter를 통해 프록시하든, 이 설정은 비용을 낮게 유지하고 생산성을 높입니다.

결론

이제 Claude Code와 함께 GPT-OSS를 사용할 준비가 되었습니다! Hugging Face에 자체 호스팅하든, OpenRouter를 통해 프록시하든, 모델 저글링을 위해 LiteLLM을 사용하든, 강력하고 비용 효율적인 코딩 설정을 갖추게 됩니다. REST API 생성부터 코드 디버깅까지 GPT-OSS는 모든 것을 제공하며, Claude Code는 이를 손쉽게 만듭니다. 사용해보고, 댓글에 좋아하는 프롬프트를 공유하고, AI 코딩에 대해 함께 이야기해 봅시다!

💡
아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

최대 생산성으로 개발팀이 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 귀하의 모든 요구 사항을 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!
버튼

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드