코딩 도구
OpenCodex
OpenCodex를 통해 Codex를 TokenLab에 연결하고 모델별 API 라우팅 설정
에이전트에게 설정 맡기기
컴퓨터에서 실행 중인 에이전트에 다음 작업을 복사하세요:
Read https://tokenlab.sh/docs/ko/integrations/opencodex and help me connect OpenCodex to TokenLab.
Check my installed OpenCodex and Codex versions, active configuration, and running proxy first.
Preserve existing accounts, providers, models, and permissions. Back up files before changing them.
Have me enter the API key locally; never ask for, print, or paste it in chat.
Use the TokenLab preset and the selected model's documented API format.
Check configuration loading first. Explain the cost before running a small real request.
Match the reply with its TokenLab request record.연결 작동 방식
OpenCodex는 Codex와 모델 API 사이의 로컬 프록시입니다. 이 가이드는 OpenCodex 2.73.0 및 Codex CLI 0.149.0을 사용합니다.
TokenLab 프리셋의 Chat Completions 통합은 2.72.0에서 릴리스 및 검증되었습니다. 버전 2.73.0은 해당 통합을 유지하면서 모델별 Responses 및 Anthropic Messages 라우팅을 추가합니다. 아래 나열된 경로는 스트리밍 텍스트 및 함수 호출/결과 왕복을 통해 TokenLab에서 확인되었습니다.
Codex는 Responses 요청을 로컬 OpenCodex 프록시로 보냅니다. 그러면 OpenCodex는 선택된 모델의 요청을 TokenLab으로 보냅니다. 로컬 연결에서의 Responses 요청이 모델이 TokenLab의 Responses API를 통해 호출된다는 의미는 아닙니다.
| Codex에서 선택한 모델 | OpenCodex → TokenLab |
|---|---|
gpt-6-astra, gpt-6.1-sol, gpt-6-sol, gpt-6-luna, grok-4.7, deepseek-v4.1-flash, deepseek-v4-pro, kimi-k3, glm-5.3 | Responses: POST /v1/responses |
claude-opus-5, claude-opus-5-5, claude-sonnet-5, claude-sonnet-5-5, claude-fable-5, claude-fable-5-1 | Anthropic Messages: POST /v1/messages |
gemini-3.8-flash | Chat Completions: POST /v1/chat/completions |
프리셋의 Base URL은 https://api.tokenlab.sh/v1입니다. 이를 변경하지 마세요. OpenCodex가 일치하는 Messages 또는 Responses URL을 직접 구성합니다. 나열된 Responses 기본값 및 Claude 라우팅 외의 모델은 프리셋의 Chat 어댑터를 사용합니다.
TokenLab은 Gemini의 네이티브 API를 선언하는 모델에 대해 이를 지원하지만, OpenCodex 2.73.0 TokenLab 프리셋은 Chat Completions를 통해 Gemini를 호출합니다. 전체 공급자를 Responses나 Gemini로 변경하지 마세요. 그렇게 하면 해당 형식을 지원하지 않는 모델에 대한 요청까지 변경될 수 있습니다.
설치 또는 업데이트
npm 설치를 위해 Node.js 18 이상을 사용하세요:
npm install -g @bitkyc08/opencodex@2.73.0
ocx --version
codex --versionCodex도 설치되어 있어야 합니다. OpenCodex는 설치 및 Codex 연결 지침을 제공합니다. 네이티브 Windows와 WSL은 별도의 구성을 가지므로, 설정과 Codex를 동일한 환경에서 실행하세요.
TokenLab 추가
TokenLab API Keys에서 키를 생성하세요. 터미널 설정의 경우, 빠른 시작를 따라 TOKENLAB_API_KEY를 설정하되 명령 기록에 값이 남지 않도록 하세요. 해당 터미널에서 OpenCodex를 시작하세요. 백그라운드 서비스는 자체 실행 환경에서 변수가 필요합니다.
새로운 OpenCodex 설치의 경우, ocx init을 실행하고 TokenLab을 선택한 다음 키를 로컬로 입력하거나 리터럴 환경 참조 ${TOKENLAB_API_KEY}를 사용하세요. 마법사의 Codex 연결 및 자동 시작 선택 사항을 검토한 후 적용하세요.
기존 설치의 경우, 다른 공급자를 대체하지 않고 프리셋을 추가하세요:
ocx provider add tokenlab --api-key '${TOKENLAB_API_KEY}'작은따옴표는 키 값이 아닌 환경 변수 참조를 저장합니다. 이 명령은 PowerShell에서도 작동합니다. tokenlab이 이미 존재하는 경우, --force로 덮어쓰지 말고 대시보드에서 해당 공급자를 편집하세요.
대시보드의 Add provider 목록에서 TokenLab을 선택하고 키를 입력할 수도 있습니다. OpenCodex는 구성을 $OPENCODEX_HOME/config.json(일반적으로 ~/.opencodex/config.json)에 저장합니다.
프록시가 실행 중이 아니라면 시작하고 대시보드를 여세요:
ocx start
ocx status
ocx gui공급자 페이지에서 Base URL과 검색된 모델을 확인하세요. 프리셋은 GET /v1/models?category=chat을 검색하며 tool-use 기능이 있는 모델을 유지합니다. 이미지, 비디오, 오디오, 임베딩 및 결정 모델은 제외됩니다. 키를 사용한 검색은 해당 키의 모델 권한 및 전달 정책을 반영합니다.
ocx sync를 실행하여 Codex를 연결하고 모델 카탈로그를 새로 고친 다음, 새로운 Codex 세션을 시작하세요. 이는 Codex의 프록시 연결 및 카탈로그를 변경하므로, 동기화 전에 기존 사용자 지정 공급자 설정을 검토하고 백업을 유지하세요. 계정이나 권한 정책을 교체할 필요는 없습니다.
모델 선택 및 요청 확인
Codex의 모델 선택기에서 tokenlab/<model-id> 항목을 선택하거나, CLI 실행 시 하나를 선택하세요:
codex -m "tokenlab/gpt-6.1-sol"OpenCodex는 tokenlab/을 사용하여 공급자를 선택합니다. TokenLab으로 전송되는 모델 ID는 gpt-6.1-sol입니다. Models에서 현재 사용 가능한 정확한 ID를 선택하세요.
간단한 연결 확인을 위해 다음을 전송하세요:
Reply only with TOKENLAB_CONNECTION_OK. Do not use tools or modify files.이 요청은 TokenLab 잔액을 사용합니다. Requests에서 응답과 일치하는 모델, 시간 및 상태를 확인하세요. 공급자 검색 및 성공적인 시작만으로는 추론 액세스가 확인되지 않습니다.
스트리밍 및 함수 호출은 표에 있는 경로에서 작동합니다. 이미지 입력 및 사고(thinking) 제어는 선택한 모델에 따라 다릅니다. 모델의 기능을 확인하고 해당 모델에 대해 OpenCodex가 제공하는 노력(effort) 선택 사항만 사용하세요. 이미지 입력 및 사고 요청은 Responses 및 Messages 경로의 대표 모델에서 확인되었습니다. Gemini 이미지 입력은 Chat 경로에서 확인되었습니다. 사고 기능을 지원하는 모델이라고 해서 반드시 사고 텍스트를 노출하거나 모든 노력 수준을 지원하는 것은 아닙니다.
Chat Completions에서 Responses 모델 유지하기
나열된 Responses 모델 중 하나에 대해 Chat 경로를 사용하려면, OpenCodex 구성의 기존 providers.tokenlab 객체에 modelAdapters 항목을 병합하세요. 다음 예시는 Codex에서 gpt-6-astra를 Chat으로 유지합니다:
{
"modelAdapters": {
"gpt-6-astra": "openai-chat"
}
}이는 공급자 필드 예시이며 전체 구성을 대체하는 것이 아닙니다. 다른 모델 재정의, 자격 증명 및 공급자를 유지한 다음 프록시를 다시 시작하고 새로운 Codex 세션을 여세요. 이 모델 항목만 제거하면 Responses 기본값으로 복원됩니다.
Claude의 Messages 라우팅은 표준 TokenLab 엔드포인트에 연결되어 있습니다. 위의 Chat 재정의는 Responses 기본값에 적용되며, Claude를 Chat으로 전환하지 않습니다. Chat 네이티브 클라이언트의 경우, 나열된 Responses 모델은 이 재정의 없이도 이미 Chat을 사용합니다. OpenCodex provider routing을 참조하세요.
전달 정책 및 기타 TokenLab 도구
이 프리셋은 X-TokenLab-Delivery-Policy 헤더를 강제하지 않습니다. TokenLab은 API 키의 전달 정책 기본값을 사용합니다. Chat, Responses 또는 Messages 선택은 전달 정책 선택과 별개입니다. TokenLab provider settings를 참조하세요.
TokenLab Skills는 통합 지침을 추가합니다. 이는 메인 모델의 공급자나 API 형식을 변경하지 않습니다.
OpenCodex 2.73.0의 JEV Auto는 TypeSafe의 결정 백엔드를 사용합니다. 해당 백엔드로 TokenLab을 제공하지 않습니다. MCP를 통해 TokenLab의 System One API를 호출하는 것은 별도의 작업입니다. TypeSafe 자격 증명 필드에 TokenLab 키를 넣지 마세요.
동일한 에이전트에서 이미지 및 비디오 생성
Codex는 TokenLab MCP server를 사용하여 이미지와 짧은 비디오를 생성할 수도 있습니다. 각 생성 비용은 동일한 TokenLab 잔액에서 차감됩니다. OpenCodex는 모델 요청만 라우팅하며, Codex 자체가 MCP 서버를 시작합니다. TOKENLAB_API_KEY가 설정된 터미널에서 Codex에 서버를 추가하세요:
codex mcp add \
--env TOKENLAB_MCP_TOOL_PROFILE=core \
--env TOKENLAB_API_KEY="$TOKENLAB_API_KEY" \
tokenlab -- \
npx -y @tokenlabai/mcp-server@0.6.48MCP는 메인 모델의 공급자나 API 형식을 변경하지 않습니다. codex mcp list를 실행하여 tokenlab이 나열되는지 확인하세요. 그런 다음 새로운 Codex 세션에서 시도해 보세요:
Call get_model_pricing for nano-banana-2, then use create_image with nano-banana-2 at 1k to make a photo of a matte black coffee mug on a white desk.create_video는 작업 ID를 반환합니다. 에이전트는 비디오가 준비될 때까지 get_task_status를 호출합니다.
문제 해결 및 설정 복원
- 선택기에 TokenLab이 없음:
ocx --version을 확인하세요. 이 가이드는 2.73.0을 대상으로 합니다.ocx sync로 카탈로그를 새로 고치고 새로운 Codex 세션을 시작하세요. - 401 또는 자격 증명 누락: 키가 활성화되어 있고 OpenCodex를 실행 중인 프로세스에서 사용 가능한지 확인하세요. 다른 터미널의 환경 변수는 이미 실행 중인 서비스를 업데이트하지 않습니다.
- 모델 누락: 정확한 ID, 키의 권한 및 현재 가용성을 확인하세요. 비채팅 모델 및
tool-use가 없는 채팅 모델은 이 프리셋에 포함되지 않습니다. - 지원되지 않는 요청 또는 잘못된 엔드포인트: 선택한 모델을 라우팅 표와 비교하고 저장된 어댑터 재정의를 검사하세요. 필수 형식은 모델 세부 정보의
tokenlab.accepted_request_formats입니다. 모델 목록이 해당 세부 정보 필드를 대체할 수는 없습니다. Claude와 Gemini는 Codex가 로컬에서 Responses를 사용한다는 이유만으로 Responses로 전송되어서는 안 됩니다. - 도구 또는 이미지 입력 실패: 원래 오류와 요청 ID를 보관하세요. 설정을 변경하기 전에 모델의 기능과 활성 OpenCodex 경로를 확인하세요. 오류를 숨기기 위해 대화 기록이나 도구 결과를 삭제하지 마세요.
Codex가 프록시를 통하지 않게 하려면 ocx stop을 사용하세요. OpenCodex는 프록시를 중지하고 네이티브 Codex 연결을 복원합니다. ocx restore는 다른 클라이언트를 위해 프록시를 계속 실행하면서 네이티브 연결을 복원합니다. 다른 클라이언트와 공유되는 설치를 변경하기 전에 OpenCodex CLI reference를 검토하세요.