kiro-gateway/docs/ko/README.md

👻 Kiro Gateway

Kiro API (Amazon Q Developer / AWS CodeWhisperer) 프록시 게이트웨이

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文 • 🇪🇸 Español • 🇮🇩 Indonesia • 🇧🇷 Português • 🇯🇵 日本語

@Jwadow가 ❤️를 담아 제작

Kiro의 Claude 모델을 Claude Code, OpenCode, Cursor, Cline, Roo Code, Kilo Code, Obsidian, OpenAI SDK, LangChain, Continue 및 기타 OpenAI 또는 Anthropic 호환 도구와 함께 사용

모델 • 기능 • 빠른-시작 • 설정 • 💖 후원

---

🤖 사용 가능한 모델

⚠️ 중요: 모델 가용성은 Kiro 플랜(무료/유료)에 따라 다릅니다. 게이트웨이는 구독에 따라 IDE 또는 CLI에서 사용 가능한 모델에 대한 액세스를 제공합니다. 아래 목록은 무료 플랜에서 일반적으로 사용 가능한 모델을 보여줍니다.

🔒 Claude Opus 4.5는 2026년 1월 17일에 무료 플랜에서 제거되었습니다. 유료 플랜에서 사용 가능할 수 있습니다 — IDE/CLI의 모델 목록을 확인하세요.

🚀 Claude Sonnet 4.5 — 균형 잡힌 성능. 코딩, 글쓰기, 범용 작업에 적합.

⚡ Claude Haiku 4.5 — 번개처럼 빠름. 빠른 응답, 간단한 작업, 채팅에 완벽.

📦 Claude Sonnet 4 — 이전 세대. 대부분의 사용 사례에서 여전히 강력하고 신뢰할 수 있음.

📦 Claude 3.7 Sonnet — 레거시 모델. 하위 호환성을 위해 제공.

💡 스마트 모델 해석: 어떤 모델 이름 형식이든 사용 가능 — claude-sonnet-4-5, claude-sonnet-4.5, 또는 claude-sonnet-4-5-20250929와 같은 버전 이름도. 게이트웨이가 자동으로 정규화합니다.

---

✨ 기능

기능	설명
🔌 OpenAI 호환 API	OpenAI 호환 도구와 함께 작동
🔌 Anthropic 호환 API	네이티브 /v1/messages 엔드포인트
🌐 VPN/프록시 지원	제한된 네트워크용 HTTP/SOCKS5 프록시
🧠 확장 사고	추론 기능은 우리 프로젝트만의 독점 기능
👁️ 비전 지원	모델에 이미지 전송
🛠️ 도구 호출	함수 호출 지원
💬 전체 메시지 기록	완전한 대화 컨텍스트 전달
📡 스트리밍	완전한 SSE 스트리밍 지원
🔄 재시도 로직	오류 시 자동 재시도 (403, 429, 5xx)
📋 확장 모델 목록	버전 모델 포함
🔐 스마트 토큰 관리	만료 전 자동 갱신

---

🚀 빠른 시작

사전 요구 사항

• Python 3.10+
• 다음 중 하나:
  • 로그인된 계정이 있는 Kiro IDE, 또는
  • AWS SSO (AWS IAM Identity Center, OIDC)가 있는 Kiro CLI - 무료 Builder ID 또는 기업 계정

설치

# 저장소 클론 (Git 필요)
git clone https://github.com/Jwadow/kiro-gateway.git
cd kiro-gateway

# 또는 ZIP 다운로드: Code → Download ZIP → 압축 해제 → kiro-gateway 폴더 열기

# 의존성 설치
pip install -r requirements.txt

# 설정 (설정 섹션 참조)
cp .env.example .env
# .env를 복사하고 자격 증명으로 편집

# 서버 시작
python main.py

# 또는 사용자 정의 포트로 (8000이 사용 중인 경우)
python main.py --port 9000

서버는 http://localhost:8000에서 사용 가능합니다

---

⚙️ 설정

옵션 1: JSON 자격 증명 파일 (Kiro IDE / Enterprise)

자격 증명 파일 경로 지정:

다음과 함께 작동:

• Kiro IDE (표준) - 개인 계정용
• Enterprise - SSO가 있는 기업 계정용

KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"

# 프록시 서버를 보호하는 비밀번호 (안전한 문자열 설정)
# 게이트웨이에 연결할 때 api_key로 사용합니다
PROXY_API_KEY="my-super-secret-password-123"

📄 JSON 파일 형식

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresAt": "2025-01-12T23:00:00.000Z",
  "profileArn": "arn:aws:codewhisperer:us-east-1:...",
  "region": "us-east-1",
  "clientIdHash": "abc123..."  // Optional: for corporate SSO setups
}

참고: ~/.aws/sso/cache/에 두 개의 JSON 파일이 있는 경우 (예: kiro-auth-token.json 및 해시 이름의 파일), KIRO_CREDS_FILE에서 kiro-auth-token.json을 사용하세요. 게이트웨이가 다른 파일을 자동으로 로드합니다.

옵션 2: 환경 변수 (.env 파일)

프로젝트 루트에 .env 파일 생성:

# 필수
REFRESH_TOKEN="your_kiro_refresh_token"

# 프록시 서버를 보호하는 비밀번호 (안전한 문자열 설정)
PROXY_API_KEY="my-super-secret-password-123"

# 선택 사항
PROFILE_ARN="arn:aws:codewhisperer:us-east-1:..."
KIRO_REGION="us-east-1"

옵션 3: AWS SSO 자격 증명 (kiro-cli / Enterprise)

AWS SSO (AWS IAM Identity Center)와 함께 kiro-cli 또는 Kiro IDE를 사용하는 경우, 게이트웨이가 자동으로 적절한 인증을 감지하고 사용합니다.

무료 Builder ID 계정과 기업 계정 모두에서 작동합니다.

KIRO_CREDS_FILE="~/.aws/sso/cache/your-sso-cache-file.json"

# 프록시 서버를 보호하는 비밀번호
PROXY_API_KEY="my-super-secret-password-123"

# 참고: AWS SSO (Builder ID 및 기업 계정) 사용자는 PROFILE_ARN 불필요
# 게이트웨이는 그것 없이도 작동합니다

📄 AWS SSO JSON 파일 형식

AWS SSO 자격 증명 파일 (~/.aws/sso/cache/에서)에는 다음이 포함됩니다:

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresAt": "2025-01-12T23:00:00.000Z",
  "region": "us-east-1",
  "clientId": "...",
  "clientSecret": "..."
}

참고: AWS SSO (Builder ID 및 기업 계정) 사용자는 profileArn이 필요 없습니다. 게이트웨이는 그것 없이도 작동합니다 (지정된 경우 무시됨).

🔍 작동 방식

게이트웨이는 자격 증명 파일을 기반으로 인증 유형을 자동 감지합니다:

• Kiro Desktop Auth (기본값): clientId와 clientSecret이 없을 때 사용

  • 엔드포인트: https://prod.{region}.auth.desktop.kiro.dev/refreshToken

• AWS SSO (OIDC): clientId와 clientSecret이 있을 때 사용

  • 엔드포인트: https://oidc.{region}.amazonaws.com/token

추가 설정 불필요 — 자격 증명 파일만 지정하면 됩니다!

옵션 4: kiro-cli SQLite 데이터베이스

kiro-cli를 사용하고 SQLite 데이터베이스를 직접 사용하려는 경우:

KIRO_CLI_DB_FILE="~/.local/share/kiro-cli/data.sqlite3"

# 프록시 서버를 보호하는 비밀번호
PROXY_API_KEY="my-super-secret-password-123"

# 참고: AWS SSO (Builder ID 및 기업 계정) 사용자는 PROFILE_ARN 불필요
# 게이트웨이는 그것 없이도 작동합니다

📄 데이터베이스 위치

CLI 도구	데이터베이스 경로
kiro-cli	~/.local/share/kiro-cli/data.sqlite3
amazon-q-developer-cli	~/.local/share/amazon-q/data.sqlite3

게이트웨이는 auth_kv 테이블에서 자격 증명을 읽습니다:

• kirocli:odic:token 또는 codewhisperer:odic:token — 액세스 토큰, 리프레시 토큰, 만료 시간
• kirocli:odic:device-registration 또는 codewhisperer:odic:device-registration — 클라이언트 ID와 시크릿

다양한 kiro-cli 버전과의 호환성을 위해 두 키 형식 모두 지원됩니다.

자격 증명 얻기

Kiro IDE 사용자:

• Kiro IDE에 로그인하고 위의 옵션 1 (JSON 자격 증명 파일) 사용
• 자격 증명 파일은 로그인 후 자동 생성됩니다

Kiro CLI 사용자:

• kiro-cli login으로 로그인하고 위의 옵션 3 또는 4 사용
• 수동 토큰 추출 불필요!

🔧 고급: 수동 토큰 추출

리프레시 토큰을 수동으로 추출해야 하는 경우 (예: 디버깅용), Kiro IDE 트래픽을 가로챌 수 있습니다:

• 다음으로의 요청 찾기: prod.us-east-1.auth.desktop.kiro.dev/refreshToken

---

🌐 VPN/프록시 지원

중국, 기업 네트워크 또는 AWS 서비스 연결에 문제가 있는 지역의 사용자를 위한 것입니다.

게이트웨이는 모든 Kiro API 요청을 VPN 또는 프록시 서버를 통해 라우팅하는 것을 지원합니다. AWS 엔드포인트에 대한 연결 문제가 발생하거나 기업 프록시를 사용해야 하는 경우 필수입니다.

설정

.env 파일에 추가:

# HTTP 프록시
VPN_PROXY_URL=http://127.0.0.1:7890

# SOCKS5 프록시
VPN_PROXY_URL=socks5://127.0.0.1:1080

# 인증 포함 (기업 프록시)
VPN_PROXY_URL=http://username:password@proxy.company.com:8080

# 프로토콜 없음 (기본값 http://)
VPN_PROXY_URL=192.168.1.100:8080

지원되는 프로토콜

• ✅ HTTP — 표준 프록시 프로토콜
• ✅ HTTPS — 보안 프록시 연결
• ✅ SOCKS5 — 고급 프록시 프로토콜 (VPN 소프트웨어에서 일반적)
• ✅ 인증 — URL에 포함된 사용자명/비밀번호

필요한 경우

상황	해결책
AWS 연결 타임아웃	VPN/프록시를 사용하여 트래픽 라우팅
기업 네트워크 제한	회사 프록시 구성
지역 연결 문제	프록시 지원이 있는 VPN 서비스 사용
개인정보 보호 요구사항	자신의 프록시 서버를 통해 라우팅

프록시 지원이 있는 인기 VPN 소프트웨어

대부분의 VPN 클라이언트는 로컬 프록시 서버를 제공합니다:

• Sing-box — HTTP/SOCKS5 프록시 지원이 있는 최신 VPN 클라이언트
• Clash — 일반적으로 http://127.0.0.1:7890에서 실행
• V2Ray — 구성 가능한 SOCKS5/HTTP 프록시
• Shadowsocks — SOCKS5 프록시 지원
• 기업 VPN — 프록시 설정에 대해 IT 부서에 문의

프록시 지원이 필요하지 않으면 VPN_PROXY_URL을 비워두세요 (기본값).

---

📡 API 레퍼런스

엔드포인트

엔드포인트	메서드	설명
/	GET	헬스 체크
/health	GET	상세 헬스 체크
/v1/models	GET	사용 가능한 모델 목록
/v1/chat/completions	POST	OpenAI Chat Completions API
/v1/messages	POST	Anthropic Messages API

---

💡 사용 예시

OpenAI API

🔹 간단한 cURL 요청

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-password-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "안녕하세요!"}],
    "stream": true
  }'

참고: my-super-secret-password-123을 .env 파일에 설정한 PROXY_API_KEY로 교체하세요.

🔹 스트리밍 요청

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-password-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "system", "content": "당신은 도움이 되는 어시스턴트입니다."},
      {"role": "user", "content": "2+2는 얼마인가요?"}
    ],
    "stream": true
  }'

🛠️ 도구 호출 포함

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-password-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "런던 날씨는 어때요?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "위치의 날씨 가져오기",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "도시 이름"}
          },
          "required": ["location"]
        }
      }
    }]
  }'

🐍 Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="my-super-secret-password-123"  # .env의 PROXY_API_KEY
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[
        {"role": "system", "content": "당신은 도움이 되는 어시스턴트입니다."},
        {"role": "user", "content": "안녕하세요!"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

🦜 LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="my-super-secret-password-123",  # .env의 PROXY_API_KEY
    model="claude-sonnet-4-5"
)

response = llm.invoke("안녕하세요, 어떻게 지내세요?")
print(response.content)

Anthropic API

🔹 간단한 cURL 요청

curl http://localhost:8000/v1/messages \
  -H "x-api-key: my-super-secret-password-123" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕하세요!"}]
  }'

참고: Anthropic API는 Authorization: Bearer 대신 x-api-key 헤더를 사용합니다. 둘 다 지원됩니다.

🔹 시스템 프롬프트 포함

curl http://localhost:8000/v1/messages \
  -H "x-api-key: my-super-secret-password-123" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": "당신은 도움이 되는 어시스턴트입니다.",
    "messages": [{"role": "user", "content": "안녕하세요!"}]
  }'

참고: Anthropic API에서 system은 메시지가 아닌 별도의 필드입니다.

📡 스트리밍

curl http://localhost:8000/v1/messages \
  -H "x-api-key: my-super-secret-password-123" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "안녕하세요!"}]
  }'

🐍 Python Anthropic SDK

import anthropic

client = anthropic.Anthropic(
    api_key="my-super-secret-password-123",  # .env의 PROXY_API_KEY
    base_url="http://localhost:8000"
)

# 비스트리밍
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요!"}]
)
print(response.content[0].text)

# 스트리밍
with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요!"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

---

🔧 디버깅

디버그 로깅은 기본적으로 비활성화되어 있습니다. 활성화하려면 .env에 추가:

# 디버그 로깅 모드:
# - off: 비활성화 (기본값)
# - errors: 실패한 요청만 로그 저장 (4xx, 5xx) - 문제 해결에 권장
# - all: 모든 요청 로그 저장 (요청마다 덮어쓰기)
DEBUG_MODE=errors

디버그 모드

모드	설명	용도
off	비활성화 (기본값)	프로덕션
errors	실패한 요청만 로그 저장 (4xx, 5xx)	문제 해결에 권장
all	모든 요청 로그 저장	개발/디버깅

디버그 파일

활성화되면 요청이 debug_logs/ 폴더에 기록됩니다:

파일	설명
request_body.json	클라이언트로부터의 수신 요청 (OpenAI 형식)
kiro_request_body.json	Kiro API로 전송된 요청
response_stream_raw.txt	Kiro로부터의 원시 스트림
response_stream_modified.txt	변환된 스트림 (OpenAI 형식)
app_logs.txt	요청에 대한 애플리케이션 로그
error_info.json	오류 세부 정보 (오류 시에만)

---

📜 라이선스

이 프로젝트는 **GNU Affero General Public License v3.0 (AGPL-3.0)**으로 라이선스됩니다.

이것은 다음을 의미합니다:

• ✅ 이 소프트웨어를 사용, 수정, 배포할 수 있습니다
• ✅ 상업적 목적으로 사용할 수 있습니다
• ⚠️ 소프트웨어를 배포할 때 소스 코드를 공개해야 합니다
• ⚠️ 네트워크 사용은 배포입니다 — 수정된 버전을 서버에서 실행하고 다른 사람이 상호 작용할 수 있게 하면 소스 코드를 그들에게 제공해야 합니다
• ⚠️ 수정 사항은 동일한 라이선스로 릴리스해야 합니다

전체 라이선스 텍스트는 LICENSE 파일을 참조하세요.

왜 AGPL-3.0인가?

AGPL-3.0은 이 소프트웨어에 대한 개선이 전체 커뮤니티에 이익이 되도록 보장합니다. 이 게이트웨이를 수정하고 서비스로 배포하는 경우 사용자와 개선 사항을 공유해야 합니다.

기여자 라이선스 계약 (CLA)

이 프로젝트에 기여를 제출함으로써 기여자 라이선스 계약 (CLA)의 조건에 동의하게 됩니다. 이것은 다음을 보장합니다:

• 기여를 제출할 권리가 있음
• 메인테이너에게 기여를 사용하고 재라이선스할 권리를 부여함
• 프로젝트가 법적으로 보호됨

---

💖 프로젝트 후원

이 프로젝트가 시간이나 돈을 절약해 주었다면 후원을 고려해 주세요!

모든 기여가 이 프로젝트를 유지하고 성장시키는 데 도움이 됩니다

🤑 기부

☕ 일회성 기부  •  💎 월간 후원

🪙 또는 암호화폐 전송

통화	네트워크	주소
USDT	TRC20	TSVtgRc9pkC1UgcbVeijBHjFmpkYHDRu26
BTC	Bitcoin	12GZqxqpcBsqJ4Vf1YreLqwoMGvzBPgJq6
ETH	Ethereum	0xc86eab3bba3bbaf4eb5b5fff8586f1460f1fd395
SOL	Solana	9amykF7KibZmdaw66a1oqYJyi75fRqgdsqnG66AK3jvh
TON	TON	UQBVh8T1H3GI7gd7b-_PPNnxHYYxptrcCVf3qQk5v41h3QTM

---

⚠️ 면책 조항

이 프로젝트는 Amazon Web Services (AWS), Anthropic 또는 Kiro IDE와 제휴, 승인 또는 후원되지 않습니다. 자신의 책임 하에 사용하고 기본 API의 서비스 약관을 준수하세요.

---

⬆ 맨 위로