Cursor · Cline · 그 밖의 도구
OpenAI 호환 주소를 넣는 곳이면 돼요.
OpenAI 호환 엔드포인트를 직접 넣을 수 있는 도구라면 전부 붙어요. 설정에서 base URL 과 키만 바꾸면 돼요.
| 넣는 곳 | 값 |
|---|---|
| Base URL / API Base | https://oneport.kr/v1 |
| API Key | sk-so-… |
| Model | /v1/models 의 id 를 그대로 |
Model 칸에는 /v1/models 에서 endpoint 가 「POST /v1/chat/completions」 인 id 만 넣으세요. gpt-5.5-pro · o3-pro · gpt-5.3-codex 처럼 endpoint 가 「POST /v1/responses」 인 모델은 이 주소로 부르면 400 이에요. Claude · Gemini 채팅 모델도 endpoint 가 이 주소라 Model 칸에 그대로 넣어요. 아래 예시의 gpt-6-sol · claude-sonnet-5 · claude-opus-5-5 는 목록에 있는 실제 id 예요 — Claude Opus 5.5 는 claude-opus-5-5 이고, claude-opus-5 는 Opus 5 라 다른 모델이에요. 목록 한 줄은 {"id": "gpt-6-sol", "endpoint": "POST /v1/chat/completions", …} 꼴이에요.
어디에 넣나요#
- Cursor — 설정의 Models 에서 OpenAI API Key 를 켜고 Override OpenAI Base URL 을 위 주소로 바꾸신 뒤, 모델 이름(gpt-6-sol · claude-sonnet-5 처럼)을 직접 추가하세요.
- Cline · Roo — API Provider 를 OpenAI Compatible 로 고르면 Base URL·Key·Model 세 칸이 그대로 나와요. Cline 도 같은 /v1/chat/completions 로 와서 도구 · 그림 번역은 Cursor 와 같아요(Cline 앱으로 따로 재 보지는 않았어요). GPT-6 · GPT-5.6 으로 도구를 쓸 땐 reasoning effort 칸을 비워 두세요 — 도구가 실린 요청에 effort 가 비어 있으면 저희가 none 을 채우고(gpt-6.2-astra · gpt-6.2-sol · gpt-6-astra · gpt-6.1-sol 빼고 · 도구가 없는 요청은 손대지 않아요), low 같은 값이 실리면 400 upstream_error 예요. Max Output 같은 출력 상한 칸 값이 max_tokens 로 실리면(도구 동작) GPT 추론 모델(GPT-5 이후 · o 계열)엔 저희가 max_completion_tokens 로 옮겨 넘기고, 미리 잡는 몫도 그 값으로 잡아요.
- LangChain · LlamaIndex — ChatOpenAI 의 base_url(또는 openai_api_base)만 바꾸시면 돼요. LangChain 은 「LangChain (Python)」 장(https://oneport.kr/docs/guides/langchain.md), Vercel AI SDK 는 「Vercel AI SDK」 장(https://oneport.kr/docs/guides/ai-sdk.md)에 예시가 있어요.
- 그 밖 — 「OpenAI 호환 주소」를 넣는 칸이 있으면 붙어요. 없으면 /v1/chat/completions 로 직접 부르셔도 같아요.
- 그림 첨부는 저희가 막지 않아요 — Claude 로 갈 때도 image_url(data: 주소 · https 주소)을 번역해 넘겨요. 다만 전송 정책을 켠 스페이스 키는 그림과 도구를 보낼 수 없어서 그림 첨부 · Agent 모드가 403 space_content_policy(code unsupported_capability)예요 — Cursor 가 Ask 에도 도구를 실으면 같아요(앱 동작). 첨부 버튼을 열어 주는지는 도구 쪽 설정이에요. 요청 한 번은 4.5MB 까지인데, 대화에 붙인 그림은 질문할 때마다 다시 실려 가서 몇 장이면 넘을 수 있어요. 넘으면 413(FUNCTION_PAYLOAD_TOO_LARGE, 영어 문장)이 와요 — 그림을 줄이거나 새 대화를 여세요.
Cursor 에서 미리 알 것#
- 채팅(Ask)은 GPT · Claude 모두 이 키로 돌아요.
- 파일을 직접 고치는 Agent 모드도 Claude 와 GPT-6 Sol 로 돼요 — 10-27 Cursor 가 보내는 것과 같은 모양의 요청을 저희가 직접 보내 도구 호출까지 재 봤어요(Cursor 앱으로 잰 건 아니에요). Agent 모드의 Cursor 는 도구를 평평한 꼴({"type": "function", "name": …})로 보내고 custom 도구({"type": "custom"} · apply_patch 같은 것)도 같이 실어요. Claude 로 갈 땐 둘 다 번역해요. GPT 로 갈 땐 둘 다 OpenAI 꼴로 접고, Cursor 가 reasoning_effort 를 안 실으니(앱 동작) gpt-6-sol · gpt-6-luna · gpt-6.1-terra · gpt-5.6-sol · gpt-5.6-terra · gpt-5.6-luna 엔 저희가 none 을 채워 넘겨요(응답 헤더 x-gateway-mapped-params 에 tools->function · tools->custom · reasoning_effort->none). gpt-6.2-astra · gpt-6.2-sol · gpt-6-astra · gpt-6.1-sol 은 이 주소로 도구를 못 받아 Agent 모드에서 400 이에요.
- Agent 모드에 넣을 모델 — GPT 는 gpt-6-sol(단가가 claude-sonnet-5 와 같아요 — 요청 한 번의 입력이 272,000 토큰 아래일 때), 더 싸게는 gpt-6-luna(gpt-6-sol 의 20분의 1)예요(Cursor 모양으로 재 본 건 claude-sonnet-5 와 gpt-6-sol 이에요 — gpt-6-luna 는 같은 none 채우기로 도구 호출을 따로 재 봤어요). Claude 는 claude-sonnet-5, 어려운 일엔 claude-opus-5-5(claude-sonnet-5 의 2배 · claude-opus-5 는 그보다 1.25배)예요(10월 기준 · 정본은 GET /v1/models). claude-sonnet-5-5 는 입력 · 출력 단가가 claude-sonnet-5 와 같고 캐시 읽기만 더 싸지만 Cursor 모양으로는 아직 안 재 봐서 claude-sonnet-5 를 권해요.
- 학생 키로 쓸 때 — 회사 · 대학 · 개인 지갑에서 만든 키는 학생 키가 아니어서 이 줄은 건너뛰셔도 돼요(한도를 걸기 전엔 지갑 잔액까지 써요). 초·중·고 학교 지갑에서 만든 키는 학생 키가 기본이에요(그 키로 GET /v1/key 를 부르면 audience 가 "student"). 학생 키가 막는 기능(403 student_key_blocked · 요금 없음)은 「인증」 장 https://oneport.kr/docs/authentication.md 에 있어요. 그중 웹 검색은 모델 회사가 대신 찾는 도구 · 칸(web_search · web_fetch · google_search · web_search_options 등)만 막아요 — 손님 쪽 함수 · custom 도구(Cursor 의 apply_patch 등 · 이름이 web_search 여도)와 그림 첨부는 안 막아서 Ask · Agent 모드는 돌아요(Cursor 의 웹 검색이 어느 쪽인지는 앱 동작이에요). 대신 월 150 크레딧 한도가 기본이고, 월 한도는 「이번 달 쓴 몫 + 이 질문이 최대로 쓸 몫」으로 재요 — 출력 상한을 안 실은 요청은 출력을 8,192 토큰으로 잡아요(Cursor 가 출력 상한을 싣는지는 앱 동작). 10월 단가로 출력 상한을 안 실으면 출력 몫만 claude-opus-5-5 약 151 · claude-opus-5 약 188 크레딧이라 기본 한도로는 한 번도 못 보내요(출력 상한을 실으면 그만큼 줄어요). claude-sonnet-5 · gpt-6-sol 은 출력 몫만 약 75 크레딧이라 입력 몫까지 더하면 Agent 모드에선 한두 번이면 막혀요. gpt-6-luna 는 출력 몫이 약 4 크레딧이에요(정본은 GET /v1/models). 학생에게 무거운 모델을 쓰게 하시려면 지갑 주인이 대시보드 키 줄의 「한도 수정」에서 월 한도를 올려 주세요. 받으신 「선생님 키」의 audience 가 "student" 면 지갑 주인이 대시보드 AI API 화면 키 목록의 쓰임새 칩을 「선생님」으로 바꾸면 돼요 — 무엇이 열리고 한도가 어떻게 바뀌는지는 「인증」 장이에요.
- Tab 자동완성은 Cursor 자체 모델이 맡아서 이 키를 쓰지 않아요.
- Cursor 는 요청을 자기 서버에서 만들어 저희에게 보내요. 키도 그 서버를 지나가요.
하루 쓰면 얼마나 드나요#
단가는 GET https://oneport.kr/v1/models 의 pricing.input_credits_per_mtok · output_credits_per_mtok(100만 토큰당 크레딧)이고, 셈은 「모델과 단가」 장에 있어요. 예를 들어 입력 100만 · 출력 10만 토큰이면 claude-sonnet-5 · gpt-6-sol 은 약 2,760 크레딧, claude-opus-5-5 는 약 5,520 크레딧, claude-opus-5 는 약 6,900 크레딧이에요(10월 단가 · 정본은 목록) — 1 크레딧은 2원이에요. 같은 양이면 gpt-6-luna 는 약 140 크레딧이에요(claude-haiku-5-5 도 단가가 같아요). gpt-6-sol · gpt-6-luna 는 요청 한 번의 입력이 272,000 토큰 이상이면 그 요청 전체가 입력 단가 2배 · 출력 단가 1.5배로 세져요(GET /v1/models 의 pricing.tier). Agent 모드와 Cline 은 질문마다 대화와 파일을 다시 보내서(앱 동작) 입력이 금방 쌓여요. gpt-6-sol · gpt-6-luna 를 쓰실 땐 도구에 넣는 대화 길이 상한(Cline 의 Context Window 칸 등)을 272,000 보다 작게(예: 200,000) 적으세요 — 목록의 context_window(1,050,000) 그대로 두면 대화가 길어질 때 이 구간에 닿아요. claude-sonnet-5 · claude-opus-5-5 엔 이런 구간이 없지만 상한을 크게 두면 질문 한 번 입력도 그만큼 커져요 — claude-sonnet-5 로 입력 20만 토큰이면 그 질문 하나 입력 몫만 약 368 크레딧이에요. claude-haiku-5-5 는 요청 한 번의 입력이 100,000 토큰을 넘으면 그 요청 전체가 입력 · 출력 · 캐시 모두 5배로 세져서(pricing.tier), 이 모델엔 상한을 100,000 보다 작게 적으세요. 새 대화도 자주 여세요. Claude 는 도구가 cache_control 을 실어 보낼 때만 캐시돼요(저희가 넣지는 않아요) — 다시 읽은 몫은 cache_read(claude-sonnet-5 는 입력의 10분의 1 · claude-sonnet-5-5 는 20분의 1), 처음 쓴 몫은 cache_write(5분 캐시는 입력의 1.25배) 단가예요. Cline 이 싣는지는 재 보지 않아서 Claude 예산은 캐시 없이 잡고, 캐시 여부는 응답 usage.prompt_tokens_details 의 cached_tokens(읽기) · cache_write_tokens(쓰기)로 보세요. gpt-6-sol · gpt-6-luna 같은 GPT-5.6 이후 모델은 실어 보내지 않아도 모델 회사가 앞부분이 같은 입력을 스스로 캐시해요(벤더 동작) — 다시 읽은 몫은 cache_read(gpt-6-sol · gpt-6-luna 는 입력의 10분의 1 · gpt-6.2-sol · gpt-6.2-astra · gpt-6.1-sol · gpt-6.1-terra 는 20분의 1), 처음 캐시에 쓴 몫은 cache_write(입력의 1.25배) 단가로 세요(10월 기준 · 정본은 목록). 오늘 이 키로 쓴 몫은 GET /v1/key 의 day.used_credits 예요(하루 한도를 안 건 키도 와요 · 호출 한 번 값은 앞뒤 차이로 재지 말고 응답 usage 토큰 × 단가로 셈하세요). 이번 달 이 키로 쓴 몫은 같은 응답의 month.used_credits 예요(한국 시간 매달 1일 0시에 0 부터 다시 세요) — 대시보드 AI API 화면의 키 목록에도 줄마다 이번 달 사용 / 한도가 보여요. 팀원 · 학생 키 여러 개를 한 번에 보시려면 지갑 주인이 만든 관리 키(sk-som-)로 GET /v1/keys 를 한 번 부르세요 — 키마다 month_used_credits · day_used_credits 로 와요(칸은 「크레딧」 장 https://oneport.kr/docs/credits.md 「키마다 한도 걸기」 · 스페이스 강좌 키는 이 목록에 없어서 그 키로 GET /v1/key 를 불러요). 지갑 전체로 지금까지 쓴 양은 GET /v1/credits 의 used_credits 예요.
팀원마다 키 · 바꾸기 · 끄기#
팀원마다 키를 따로 만드세요 — 크레딧을 산 곳(스쿨오더 · 오피스오더) 대시보드의 AI API 화면에서 만들고, 키 줄의 「한도 수정」에서 월 · 하루 한도와 기한을 걸어요. 키는 모두 한 지갑을 같이 써요. 키를 바꿀 땐 그 키 줄의 「새로 받기」를 누르세요 — 이름 · 한도 · 기한 · 쓰임새가 새 키로 넘어가고 이번 달 · 오늘 쓴 몫도 이어져요. 옛 키는 바로 꺼지니 Cursor · Cline 의 API Key 칸만 새 키로 바꾸면 돼요(Base URL · 모델은 그대로). 나간 팀원의 키는 「폐기」로 꺼요 — 되돌릴 수 없어요(관리 키로는 DELETE /v1/keys/{id}).
안 될 때#
- 요금 없이 확인하기 — 키는 GET /v1/key 로 확인하세요(요금이 안 붙고, 틀리면 401 이 이유를 말해요). 키를 붙인 GET /v1/models 도 틀린 키 · 못 읽은 키 머리글(「Bearer 」 빠짐 등)이면 같은 401 이에요. 모델 이름 오타(404) · 잔액 부족(402)도 요금이 붙기 전에 나요 — 다만 글 문은 잔액을 먼저 봐서, 크레딧이 없으면 이름이 틀려도 402 예요. 그래서 목록에 없는 이름으로 보내 404 model_not_found 가 오면 키 · 주소는 맞고 잔액도 최소치는 넘는다는 뜻이에요 — 키의 월 · 하루 한도는 모델을 찾은 뒤에 재서 학생 키도 같은 404 가 오고, 실제 모델은 429 일 수 있어요. 크레딧이 아직 없어도 /v1/key · /v1/credits 는 돼요. /v1/models 는 키 없이 부르면 파는 모델이 다 오고, 키를 붙이면 그 키로 부를 수 있는 모델만 와요 — 크레딧이 한 번도 안 들어온 키는 무료 검열 모델(omni-moderation-…) 줄만 와요(credit_scope.label 「아직 없음」). 연결이 틀린 게 아니라 충전 전이라는 뜻이에요. 실제 답을 받는 확인은 짧은 질문 하나로 하세요(아주 적은 요금이 붙어요): curl -s https://oneport.kr/v1/chat/completions -H "Authorization: Bearer $ONEPORT_API_KEY" -H "Content-Type: application/json" -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"안녕"}]}' — GPT 로 재실 땐 max_tokens 를 아주 작게 두지 마세요. 생각하는 토큰도 이 상한에 들어가요.
- 모델 목록이 안 뜬다 — 주소 끝의 /v1 이 빠지면 목록 요청이 404 「주소에 /v1 이 빠졌어요」를 받아요. https://oneport.kr/v1 로 넣으세요. 이름을 직접 적으면 돌아가지만 크레딧이 있어야 해요(없으면 402).
- 402 가 온다 — 문장에 「다른 호출이 잡아 둔 몫」이 있으면(error.reason held_by_others) 같은 지갑의 다른 요청 몫 때문이라 잠시 뒤(Retry-After: 5) 그대로 다시 보내요. 「미리 잡는 몫 대부분이 입력」이 붙었으면 대화나 첨부가 커서라 새 대화를 여세요. 그 밖엔 GET /v1/credits 의 balance_credits 를 보고 충전해요.
- 429 가 온다 — Cursor 화면엔 저희 오류 문장이 그대로 보일 수 있어요(앱 동작). error.type 이 key_limit_exceeded 면 이 키의 하루 · 월 한도라 그대로 다시 보내면 같아요(x-should-retry: false). error.reason 이 key_month_limit(「이 키의 이번 달 남은 한도로는 …」 — 학생 키는 문장이 달라서 문장 말고 reason 으로 가르세요)이면 GET /v1/key 의 month.remaining_credits 를 보세요 — 남아 있으면 이 질문의 최대 몫이 남은 몫보다 커서 막힌 거라 새 대화를 열거나(입력 몫이 줄어요) gpt-6-luna 처럼 단가가 낮은 모델로 바꾸면 지나갈 수 있고, 0 이면 바꿔도 같아요. 「이 키의 오늘 사용 한도에 닿았어요. 한국 시간 내일 0시에 다시 열려요.」(key_day_limit)면 바꿔 보내도 같아요. 둘 다 지갑 주인이 대시보드 키 줄의 「한도 수정」에서 올리면 바로 풀려요. 스페이스 강좌 키의 429 group_limit_exceeded 는 error.reason 으로 갈라요(「에러」 장). 다만 error.reason 이 held_by_others 면 같은 키로 아직 끝나지 않은 다른 요청 몫 때문이라 잠시 뒤 다시 보내면 돼요(x-should-retry: true · Retry-After: 5). rate_limit_error 면 모델 회사가 잠깐 몰린 거라 잠시 뒤 다시 보내면 돼요. 화면에 reason 이 안 보이면(앱 동작) 문장으로 가르세요 — 「이 키의 오늘 사용 한도에 닿았어요. …」는 학생 키도 같은 하루 한도 문장이고, 「다른 호출이 잡아 둔 몫」이 든 문장은 held_by_others, 그 밖의 key_limit_exceeded 문장은 월 한도예요.
- temperature 는 걱정 안 하셔도 돼요 — OpenAI 형식 도구가 습관처럼 싣는 이 값을 Claude 5 세대와 GPT 추론 모델(GPT-5 · 5.5 · 5.6 · 6 · o 계열)로 갈 땐 저희가 빼고 넘기고, 응답 헤더 x-gateway-ignored-params 에 적어요. 이 주소로 부르시면 이 400 은 안 나요.
- GPT-5.6·GPT-6 에서 도구를 쓰면 400 이 난다 — 목록에서 display_name 이 GPT-6 · GPT-5.6 으로 시작하는 모델이에요. 이 문에선 도구와 추론을 같이 못 써요. 400 이 나면 도구 설정이 none 이 아닌 값을 싣고 있거나 gpt-6.2-astra · gpt-6.2-sol · gpt-6-astra · gpt-6.1-sol 이에요 — reasoning_effort 를 none 으로 바꾸시거나, Responses API 로 붙는 설정이 있으면 그쪽을, 아니면 Claude 모델을 쓰세요. 이 400 은 error.type 이 upstream_error 이고 문장에 OpenAI 의 이유(Function tools with reasoning_effort …)가 그대로 와요 — 요금은 안 붙어요.
- 504 가 온다 — error.reason 이 timeout 이면 모델 회사가 실행하기 전에 저희 처리 기한(4분)이 끝난 거예요. 요금은 안 붙었어요. 몇 초 뒤 한 번 그대로 다시 보내세요 — x-should-retry: false 가 붙어서 도구가 스스로 다시 보내지 않을 수 있어요(앱 동작). 422 upstream_execution_unconfirmed 는 자동으로 다시 보내지 마세요(아래 줄).
- 스트리밍이 중간에 끊긴다 — 조각 사이가 120초 넘게 비거나 시작부터 약 12분 50초가 지나면 끊겨요. 아주 긴 답은 나눠 물어보시면 안정적이에요. 모델 회사로 보낸 뒤 첫 응답이 120초 안에 안 오면 422 upstream_execution_unconfirmed 로 끝나요. x-should-retry: false 가 붙고 Retry-After 는 없어요. 같은 요청을 자동 재전송하지 마세요. Idempotency-Key 를 실어 보낸 요청이면 받은 x-gateway-status-url 을 같은 API 키로 GET 조회하세요. Idempotency-Key 없이 보낸 요청엔 조회 주소가 안 오고 요청 ID 로 만든 주소로는 조회가 안 돼요 — 요청 ID 와 부른 시각을 admin@schoolorder.kr 로 알려 주세요.
- 문의하실 땐 — 응답 머리글 request-id(같은 값이 x-request-id 로도 와요 · 오류 몸통엔 error.request_id)와 부른 시각 · 모델 이름을 같이 admin@schoolorder.kr 로 보내주세요. 모델 회사까지 간 응답이면 x-gateway-fallback-depth 도 알려 주세요(401 · 402 · 키 한도 429 처럼 부르기 전에 막힌 응답엔 없어요). Cursor · Cline 화면에서 머리글을 볼 수 없으면 기존 오류 기록과 부른 시각 · 모델 이름으로 문의해 주세요. 실행 불명인 요청의 ID를 얻으려고 새 요청을 보내지 마세요.
원래대로 되돌리기#
설정에서 Base URL 과 키를 원래 값으로 돌리시면 끝이에요. 도구 쪽에 저희가 심는 건 없어요.