Ox Alpha를 클로드 코드와 코덱스 CLI에서 쓰는 방법
Ox Alpha로 알려진 GLM-5.3-Flash를 기존 코딩 도구에 연결할 때 확인할 주소, 모델과 설정 파일을 설명합니다. 설정 백업부터 작은 요청의 결과와 사용량 확인, 원래 환경 복구까지 안내합니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
Ox Alpha는 Z.AI가 이름을 감춘 채 공개했던 GLM-5.3-Flash입니다. 클로드 코드와 코덱스 CLI는 모두 Z.AI가 공식으로 지원하는 도구라, 도구를 다시 설치하지 않고 연결 제공자와 모델 설정을 바꿀 수 있습니다. 다만 모델 이름만 바꾸는 일이 아닙니다. 요청 내용과 비용 처리가 Z.AI로 넘어가며 도구의 모든 기능이 똑같이 호환된다는 보장도 없습니다.
스텔스 모델로 등장했던 Ox Alpha가 정체를 드러낸 뒤 자연스럽게 따라오는 질문이 하나 있습니다. 무료 기간에 써 봤다면 평소 쓰는 터미널 도구에도 그대로 붙일 수 있는지입니다. 결론부터 적으면 붙일 수 있고 방법도 공식 문서에 정해져 있습니다. 다만 두 도구가 쓰는 설정 파일과 주소가 서로 달라서, 한쪽 설정을 다른 쪽에 그대로 옮기면 동작하지 않습니다.
이 글은 8월 27일 작성했고 설정 절차는 2026년 10월 4일 공식 문서와 대조했습니다. 아래 코드는 문서 기반 예시이며 실제 결제와 연동 실행을 검증한 기록은 아닙니다.
시작 전에 준비할 것과 이번 연습 범위
클로드 코드나 코덱스 CLI가 이미 실행되는 분을 위한 연동 안내입니다. CLI는 터미널에서 명령을 입력해 쓰는 방식입니다. 아직 설치하지 않았다면 클로드 코드 설치 또는 코덱스 설치부터 진행합니다.
Z.AI 사용 권한과 해당 플랜의 API 키가 필요합니다. API 키는 요청 권한을 증명하는 비밀값입니다. 앤트로픽이나 ChatGPT 구독이 Z.AI 사용료를 대신 내주지는 않습니다. Team Coding Plan은 팀 전용 키가 필요하며 다른 종류의 Z.AI 키와 바꿔 쓸 수 없습니다.
먼저 설정을 바꾸지 않고 아래 주소 표에서 ‘클로드 코드’와 ‘코덱스 CLI’의 주소를 찾아 메모합니다. 둘을 바꾸어 적었을 때 어느 부분을 고쳐야 하는지 설명할 수 있으면 첫 확인을 마친 것입니다. 아직 결제할 계획이 없다면 여기서 멈춰도 됩니다.
실제로 연결할 때에는 도구 하나만 고릅니다. 사용하던 모델과 설정 경로를 메모하고, 기존 설정 파일을 저장소 밖의 개인 폴더에 날짜를 붙여 복사합니다. 파일에는 비밀값이 들어 있을 수 있으므로 백업도 공유하지 않습니다. 기존 파일이 없었다면 그 사실을 기록합니다.
| 도구 | macOS와 리눅스의 기본 경로 | 윈도우 기본 경로 |
|---|---|---|
| 클로드 코드 | ~/.claude/settings.json | %USERPROFILE%\.claude\settings.json |
| 코덱스 CLI | ~/.codex/config.toml | %USERPROFILE%\.codex\config.toml |
~와 %USERPROFILE%은 내 사용자 폴더를 뜻합니다. 별도 설정 폴더나 WSL을 쓴다면 실행 중인 도구가 실제로 읽는 경로를 확인합니다. Finder의 ‘폴더로 이동’이나 파일 탐색기의 주소창으로 폴더를 열고 텍스트 편집기로 수정합니다. 설정 내용은 AI 대화 입력란에 붙이지 않습니다.
클로드 코드와 코덱스 모두 공식 지원 목록에 있습니다
위 화면은 Z.AI 개발자 문서의 지원 도구 목록입니다. 클로드 코드와 코덱스가 나란히 올라 있고, OpenCode와 Cursor 등도 연동 안내를 제공합니다. 지원 목록은 달라질 수 있으므로 개수보다 사용할 도구의 안내를 확인합니다.
Z.AI는 자체 도구 외에 기존 코딩 도구의 연동도 제공합니다. 코덱스 CLI와 클로드 코드 비교에서 다룬 사용 방식은 유지할 수 있지만, 모델을 바꾸면 응답과 지원 기능은 달라질 수 있습니다.
도구는 그대로 두고 주소만 바꾸는 방식
클로드 코드는 앤트로픽 서버로 요청을 보내도록 만들어져 있습니다. 그 주소를 Z.AI로 바꾸면 같은 프로그램이 같은 형식으로 편지를 쓰되 배달지만 달라집니다. Z.AI가 앤트로픽 형식으로 받아 GLM 모델로 처리한 뒤 다시 같은 형식으로 돌려주기 때문에, 기본 요청 형식을 맞출 수 있습니다. 기능과 도구 호출의 호환성은 작은 작업으로 별도 확인합니다.
봉투 형식이 도구마다 다르다는 점만 주의하면 됩니다. Z.AI는 세 가지 형식을 받고 주소를 따로 두고 있습니다.
| 형식 | 주소 | 쓰는 도구 |
|---|---|---|
| Anthropic Messages | https://api.z.ai/api/anthropic | 클로드 코드 |
| OpenAI Chat Completions | https://api.z.ai/api/coding/paas/v4 | Cline, Roo Code 등 |
| OpenAI Responses | https://api.z.ai/api/v1 | 코덱스 CLI |
문서는 이 대목에 경고를 하나 달아 두었습니다. 도구에 맞지 않는 주소를 넣으면 구독 사용량이 적용되지 않는다는 내용입니다. 잘못된 주소가 항상 다른 요금으로 자동 결제된다는 뜻은 아닙니다. 인증이나 연결 오류가 날 수도 있으므로, 설정 직후 주소와 사용량을 확인합니다.
클로드 코드 설정
위 화면이 이 글의 질문에 답하는 대목입니다. 클로드 코드가 안에서 쓰는 모델 항목 세 개를 모두 GLM-5.3-Flash로 채우는 것이 문서가 안내하는 기본값입니다. Ox Alpha로 알려졌던 그 모델이 오퍼스 항목까지 대신한다는 뜻입니다.
Z.AI의 도우미는 설치와 설정을 자동으로 바꿀 수 있는 선택 사항입니다. 아래 수동 방법과 동시에 실행하지 않습니다. 도우미를 쓸 때에도 먼저 백업하고 변경 대상을 확인합니다.
npx @z_ai/coding-helper수동으로 하려면 settings.json의 기존 env 안에 아래 항목을 추가하거나 수정합니다. 파일 전체를 이 예제로 바꾸거나 env를 두 번 만들지 않습니다. your_zai_api_key는 개인 편집기에서 실제 키로 교체하는 표시이며, 키가 들어간 파일을 Git이나 온라인 JSON 검사기에 올리지 않습니다.
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "your_zai_api_key",
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5.3-flash[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.3-flash[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.3-flash[1m]",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"API_TIMEOUT_MS": "3000000"
}
}모델 이름 뒤의 [1m]은 Z.AI 안내에서 100만 토큰 컨텍스트를 요청하는 표시입니다. 컨텍스트는 한 번에 참고할 수 있는 내용의 용량이며 구독 사용량 한도와 다릅니다. 함께 제시한 설정 가운데, CLAUDE_CODE_AUTO_COMPACT_WINDOW는 대화가 길어졌을 때 자동으로 요약을 시작하는 시점이고 API_TIMEOUT_MS는 응답을 기다리는 한계 시간입니다. 3,000,000밀리초는 50분입니다. 이 값은 기다리는 한계이지 작업 완료 시간이나 한도 증가가 아닙니다. 처음에는 짧은 요청으로 확인합니다.
설정을 저장한 뒤 진행 중인 작업을 정리하고 해당 클로드 코드 세션을 종료합니다. 새 터미널에서 연습 폴더를 열고 claude를 실행합니다. 문서가 이 순서를 따로 적어 둔 이유는 이미 떠 있는 창이 옛 설정을 그대로 들고 있기 때문입니다.
문서 안에서 값이 어긋나는 곳도 하나 눈에 띕니다. 안내 문단은 세 항목을 모두 GLM-5.3-Flash로 적어 두었는데, 같은 페이지의 수동 설정 예시에는 소네트와 오퍼스 항목이 glm-5.3으로 적혀 있습니다. 모델 전환을 다루는 다른 문서는 다시 세 항목을 모두 glm-5.3-flash[1m]으로 안내합니다. 차이의 원인을 단정할 수는 없습니다. 이 글은 Flash를 쓰는 목적에 맞춰 모델 전환 안내의 세 가지 값을 적용한 예시입니다. /status에서 실제 모델이 glm-5.3-flash인지와 설정 출처를 확인합니다. 기존에 모델을 직접 지정했다면 /model sonnet으로 매핑된 모델을 선택하고 다시 확인합니다. 그래도 다르면 요청하지 말고 실행 옵션과 프로젝트 또는 조직 설정의 우선순위를 확인합니다.
코덱스 CLI 설정
코덱스는 config.toml 외에 모델의 기능을 알려 주는 목록 파일도 준비합니다. Z.AI의 Codex 공식 안내의 ‘Create the Model Catalog File’ JSON을 ~/.codex/zai-models.json이라는 새 파일에 저장합니다. 기존 models.json을 덮어쓰지 않도록 이름을 구분한 것입니다. zai-models.json도 이미 있으면 다른 새 이름을 정하고 아래 경로도 함께 바꿉니다. 윈도우는 사용자 폴더의 .codex 안에 저장합니다.
공식 예시는 일반 모델인 glm-5.3입니다. Ox Alpha에 해당하는 Flash를 쓰려면 복사한 목록에서 slug와 display_name을 모두 glm-5.3-flash로 바꾸고, 아래 설정의 model과 맞춥니다. 설명인 description도 Flash 모델이라고 고칩니다. 이번 연습은 텍스트 요청만 다룹니다. 이 수정은 모델을 새로 만드는 일이 아니라 제공되는 모델을 도구에 알려 주는 일입니다.
기존 config.toml에서 아래 최상위 항목을 찾고 필요한 값만 바꿉니다. 최상위 항목은 [다른 섹션] 아래에 넣지 않습니다. [model_providers.ZAI]가 이미 있으면 그 안의 값을 수정하고 중복 섹션을 만들지 않습니다.
model_provider = "ZAI"
model = "glm-5.3-flash"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/zai-models.json"
[model_providers.ZAI]
name = "ZAI"
base_url = "https://api.z.ai/api/v1"
env_key = "ZAI_API_KEY"
wire_api = "responses"model_catalog_json에는 실제 저장한 파일 경로를 넣습니다. 윈도우에서 절대 경로를 적을 때는 C:/Users/내사용자이름/.codex/zai-models.json처럼 슬래시를 쓸 수 있습니다. high는 짧은 첫 요청을 위한 예시이며 Z.AI의 원래 예시는 max입니다. 추론 노력은 답을 만들 때 들일 계산을 조절합니다.
env_key는 비밀키 자체가 아니라 키를 읽을 환경 변수의 이름입니다. 오픈AI는 설정 파일에 토큰을 직접 넣는 experimental_bearer_token보다 이 방식을 권합니다. 두 인증 항목을 함께 두지 않습니다. 기존 ZAI 섹션에 다른 인증 설정이 있으면 변경 전 값을 기록하고 이번 방식과 중복되지 않도록 확인합니다. 설정 공식 문서
별도 프로필로 시작하면 이 파일의 값보다 프로필 설정이 우선할 수 있습니다. 기존 실행 방식과 /status를 함께 확인합니다.
새 터미널에서 본인이 만든 빈 연습 폴더로 이동합니다. cd 다음에 폴더 경로를 입력하거나 끌어다 놓고 Enter를 누릅니다. Mac 기본 zsh 터미널에서는 다음 명령을 한 줄씩 실행합니다. 키 입력 안내가 나오면 키를 붙이고 Enter를 누릅니다. 입력 내용은 화면에 보이지 않습니다.
read -s 'ZAI_API_KEY?Z.AI API key: '
export ZAI_API_KEY
codex윈도우 PowerShell에서는 다음과 같습니다.
$zaiSecret = Read-Host 'Z.AI API key' -AsSecureString
$env:ZAI_API_KEY = [System.Net.NetworkCredential]::new('', $zaiSecret).Password
Remove-Variable zaiSecret
codex환경 변수는 해당 터미널에서 시작한 프로그램으로 전달됩니다. 같은 터미널에서 codex를 실행하고 /status에서 제공자와 모델을 확인합니다. 키를 입력한 뒤 새 창으로 옮기면 그 창에는 변수가 없을 수 있습니다. 리눅스 등 다른 셸에서는 해당 셸의 비밀 입력 방법을 사용합니다.
짧은 요청으로 결과와 사용량 확인하기
현재 설정이 맞는지 확인한 뒤, 선택한 도구의 AI 대화 입력란에 아래 가상 자료를 넣습니다. 이 단계부터 실제 Z.AI 사용량이 발생할 수 있습니다.
아래 두 항목의 개수 합계를 한 문장으로 알려 주세요.
사과 3개, 배 2개입니다.
파일 수정이나 외부 도구 실행은 하지 마세요.합계가 틀리면 ‘사과 3개와 배 2개를 더해 다시 계산해 주세요’라고 요청하고 대조합니다. 합계 5개가 맞는지 보고 사과만 4개로 바꿔 다시 계산해 주세요라고 요청합니다. 결과는 6개입니다. AI에게 정체를 물어 답한 모델명을 증거로 쓰지 않고, 도구 상태와 Z.AI의 사용 내역을 함께 확인합니다. 사용 내역 반영이 늦을 수 있으므로 올바른 계정인지 확인하고 사용량 화면을 새로고침합니다. 처음 메모한 플랜에서 차감되는지 여전히 불분명하면 추가 요청을 멈추고 시각과 오류 문구를 남겨 지원에 문의합니다.
혼자 반복할 때에는 새 대화에 같은 지시를 넣고 사과 2개, 배 5개로 바꿉니다. 7개인지 대조하고 그동안 사용량이 어떻게 기록됐는지 확인합니다. 이 연습은 연결과 간단한 결과 확인이며 파일 편집과 모든 도구의 호환성을 보장하지 않습니다.
오류가 나면 다음 순서로 확인합니다.
- 인증 오류: 키 종류와 계정, 키를 읽는 위치를 확인합니다. 키 원문을 화면 공유나 질문에 넣지 않습니다.
- 모델 또는 목록 오류:
zai-models.json의 존재와 JSON 형식,slug와 설정 모델 이름의 일치를 확인합니다. - 설정 오류: JSON의 쉼표, TOML의 중복 섹션과 항목 위치를 로컬 편집기에서 확인합니다. 설정 파일을 삭제하는 것으로 해결하지 않습니다.
- 요청이 예상과 다르게 진행됨: Esc로 현재 요청을 중단하고 실행 내용을 확인한 뒤 범위를 다시 지정합니다.
요금제와 사용량 한도
이 방식은 무료가 아닙니다. Z.AI의 GLM Coding Plan을 구독하거나 API를 종량으로 결제해야 합니다. 공식 문서가 밝힌 플랜별 한도는 다음과 같습니다.
| 플랜 | 5시간 크레딧 | 주간 크레딧 |
|---|---|---|
| Lite | 2,000 | 10,000 |
| Pro | 12,000 | 60,000 |
| Max | 28,000 | 140,000 |
개요 페이지는 월 18달러부터라고 안내하지만 실제 플랜과 결제 주기, 할인은 결제 화면에서 확인합니다. 크레딧은 사용량 계산 단위이며 요청 횟수나 토큰 수와 같지 않습니다. 5시간 크레딧은 쓰고 나서 5시간 뒤에 다시 차고, 주간 크레딧은 일주일마다 초기화됩니다. 모든 플랜이 GLM-5.3과 GLM-5.3-Flash를 지원하며 공식 안내의 일부 이전 모델 ID는 새 모델로 연결됩니다. 모든 ID가 같은 모델로 바뀌는 것은 아닙니다. 할인 기간도 변할 수 있으므로 현재 차감 조건을 확인합니다.
원래 모델로 돌아가기
작업을 마친 뒤 해당 세션을 종료합니다. 백업 이후 다른 변경이 없다면 원래 설정 파일로 복구합니다. 다른 설정도 추가했다면 파일 전체를 덮어쓰지 말고 이번에 바꾼 항목만 원래 값으로 돌립니다. 처음 없던 항목만 제거하고 기존 값은 복원합니다.
코덱스용 모델 목록은 다른 설정에서 참조하지 않는지 확인한 뒤 이번에 만든 파일만 정리합니다. 터미널의 키도 Mac zsh에서는 unset ZAI_API_KEY, PowerShell에서는 Remove-Item Env:ZAI_API_KEY로 지웁니다. 새 세션의 /status에서 원래 모델과 제공자로 돌아왔는지 확인합니다.
두 제공자를 자주 오간다면 도구가 지원하는 별도 설정이나 프로필 방식을 검토할 수 있습니다. ‘설정 파일이 하나이므로 두 제공자는 절대 동시에 못 쓴다’는 뜻은 아닙니다. 이 글은 한 도구의 설정을 바꿨다가 복구하는 첫 연습만 다룹니다.
로컬에 내려받은 가중치로도 클로드 코드에 붙일 수 있나요?
가능하지만 서버 실행과 API 호환 설정을 따로 익혀야 합니다. GLM-5.3-Flash는 MIT 라이선스로 공개됐고 현재 공식 모델 카드는 vLLM과 SGLang 등 여러 실행 도구를 안내합니다. OpenAI 호환 주소가 생겼다고 Anthropic 형식의 모든 요청도 바로 처리되는 것은 아니므로 도구별 연결 방식을 확인합니다.
총 파라미터는 3,200억 개이고 요청 처리에 활성화되는 것은 180억 개입니다. 활성 파라미터가 적다고 저장할 전체 모델 크기도 180억 규모가 되는 것은 아닙니다. 양자화 방식과 실행 도구, 메모리 및 장비 구성이 필요하므로 API 비용을 없애려는 목적만으로 노트북에서 바로 실행할 수 있다고 판단하지 않습니다.
참고 자료
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
기존 설정 파일에 Z.AI 예제를 적용할 때 먼저 할 일은 무엇인가요?
이 글이 도움이 되었나요?
코딩 에이전트가 무엇이고 도구마다 무엇이 다른지, 비개발자 눈높이로 고르는 기준까지
코스 전체 보기 →
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.