ZCode에 내 AI 키 연결하기

1ZCode 설치하기

ZCode는 대화로 코드를 만들고 고치는 데스크톱 앱입니다. 설치 파일은 공식 다운로드 페이지(zcode.z.ai/en)에서 받습니다. 페이지 맨 아래 'All Downloads'에 운영체제별 설치 파일이 모여 있습니다.

처음 실행 화면에서 계정 연결 건너뛰기

ZCode를 처음 실행하면 계정을 연결하라는 'Welcome to ZCode' 화면이 나옵니다. 이번 행사에서는 서울라우트 키를 쓰기 때문에 ZCode 쪽 계정이나 유료 구독이 필요하지 않습니다. 위쪽의 검은 버튼 두 개(Connect to Z.ai, Connect to BigModel)는 누르지 않습니다.

1. ①맨 아래의 Use API key를 누릅니다.

1. ②창 맨 아래의 Skip for now(지금은 건너뛰기)를 누릅니다. 이 창의 API key 칸은 다른 서비스의 키를 넣는 곳입니다. 서울라우트 키는 여기에 넣지 않고 3단계에서 넣습니다.

건너뛰면 바로 작업 화면이 열립니다. 왼쪽 아래에 'Connect'가 보여도 누르지 않습니다.

2내 연결 정보 확인하기

ZCode에 넣을 값은 내 개인 페이지에 모두 있습니다. 개인 페이지는 참가자마다 따로 있고 키도 사람마다 다릅니다.

1. ①브라우저에서 kongju.seoulroute.ai를 열고 카드에 적힌 개인 코드를 입력합니다.
2. ②열기를 누릅니다. 카드의 QR 코드를 휴대폰으로 스캔해도 같은 페이지가 열립니다.

개인 페이지 위쪽에는 남은 이용 한도가 보입니다. 금액(US$)과 비율(%)이 함께 나오고 새로 고침을 누르면 최신 값으로 바뀝니다. 사용 기록은 몇 분 늦게 반영될 수 있습니다. 키는 11월 1일(일) 24:00까지 쓸 수 있습니다.

아래쪽 'ZCode에 넣을 값' 카드에는 3단계부터 쓸 값이 모여 있습니다. 값마다 옆의 복사 버튼을 누른 뒤 ZCode에 붙여넣으면 오타가 생기지 않습니다.

1. ①Base URL 복사 버튼입니다.
2. ②API key 복사 버튼입니다. 키는 처음에 가운데가 가려져 있습니다. 복사 버튼은 가려진 상태에서도 전체 키를 복사합니다. 보기는 옆 사람이 볼 수 있으니 꼭 필요할 때만 누릅니다.
3. ③Model ID 복사 버튼입니다. 기본 추천 모델은 glm-5.3입니다. 빠른 응답이 필요하면 glm-5.3-flash를, 이전 버전과 비교하고 싶으면 glm-5.2를 씁니다.

정리하면 ZCode에 넣을 값은 다음과 같습니다.

3서울라우트 공급자 만들기

이제 ZCode에 서울라우트 연결 정보를 저장합니다. ZCode 창 왼쪽 아래의 설정을 엽니다.

1. ①왼쪽 아래 톱니바퀴 모양의 설정(Settings) 버튼을 누릅니다.

1. ①설정 화면 왼쪽 메뉴에서 Model settings를 누릅니다.
2. ②오른쪽 위의 + Add provider를 누릅니다.

오른쪽의 Z.ai 안내 카드에 있는 Connect to Z.ai와 요금제 안내는 누르지 않습니다.

1. ③목록의 'Other' 아래에서 Create custom provider를 한 번만 누릅니다.

누르자마자 왼쪽 목록에 'New provider'가 추가됩니다. 따로 저장 버튼이 없으니 여러 번 누르지 않습니다. 실수로 여러 개가 생겼다면 남는 것은 9단계의 방법처럼 … → Delete로 지웁니다.

1. ①New provider 오른쪽 위의 …(More) 버튼을 누릅니다.
2. ②Rename을 누르고 이름 칸의 글자를 지운 뒤 서울라우트라고 입력합니다. Return(Windows는 Enter)을 누르면 이름이 바뀝니다.

이제 연결 정보 세 가지를 넣습니다. 각 값은 개인 페이지에서 복사해 붙여넣습니다.

1. ①Base URL 칸을 누르고 https://kongju.seoulroute.ai/v1을 붙여넣습니다. 끝의 /v1까지 그대로 넣고 뒤에 다른 글자를 덧붙이지 않습니다.
2. ②API format 목록을 엽니다. 처음에는 다른 형식이 골라져 있습니다. 목록에서 Chat completions (/chat/completions)를 고릅니다. 다른 항목은 고르지 않습니다.
3. ③API key 칸을 누르고 개인 페이지에서 복사한 키를 붙여넣습니다. 칸 오른쪽의 눈 모양 아이콘은 키를 그대로 보여 주는 버튼이니 누르지 않습니다.

입력한 값은 바로 저장됩니다. 왼쪽 목록에 '서울라우트'가 보이면 다음 단계로 넘어갑니다.

4모델 추가하고 연결 시험하기

공급자에 어떤 모델을 쓸지 알려 줍니다. [그림 11]의 ④ + Add model을 누르면 모델 추가 창이 열립니다.

1. ①Model ID 칸에 glm-5.3을 붙여넣습니다. 대·소문자와 점까지 똑같이 넣습니다.
2. ②Save를 누릅니다.

Smart configuration(자동 설정)은 켜 둔 채로 둡니다. Model ID를 넣고 잠시 기다리면 'Smart configuration matched for this model'(자동 설정 완료)이라는 초록 문구가 뜹니다. 문구가 사라져 Save 버튼 위치가 바뀔 수 있으니 버튼을 확인하고 누릅니다. Context window와 Max output tokens 칸의 회색 숫자는 ZCode가 모델 이름을 보고 미리 채운 값이므로 비워 둬도 됩니다. 행사 전 시험에서도 이 기본값 그대로 작업이 잘 됐습니다.

같은 방법으로 + Add model을 두 번 더 눌러 glm-5.3-flash와 glm-5.2도 추가합니다. 세 모델을 모두 넣어 두면 나중에 모델을 바꿔 가며 쓸 수 있습니다.

Advanced settings(고급 설정)는 건드리지 않아도 됩니다

Advanced settings를 펼치면 입력 형식, 모델 기능, 추론 수준(Reasoning levels) 같은 값이 보입니다. 자동 설정이 추론 수준을 low·high·max로 채워 두므로 바꿀 필요가 없습니다.

모델을 저장했으면 연결이 되는지 바로 시험합니다.

1. ①모델 목록에서 glm-5.3 줄의 플러그 모양 아이콘을 누릅니다. 잠시 뒤 아래쪽에 '서울라우트 / glm-5.3 connected'라는 초록색 알림이 뜨면 성공입니다.

'Failed to connect'로 시작하는 알림이 뜨면 연결에 실패한 것입니다. 알림 뒤쪽의 한국어 문구를 읽고 8단계 문제 해결 표에서 같은 문구를 찾습니다. 예를 들어 'API 키가 올바르지 않습니다'가 보이면 키를 다시 복사해 붙여넣습니다. 연결 시험도 이용 한도를 아주 조금 씁니다.

설정이 끝났으면 설정 화면 왼쪽 위의 ← Back to workspace를 눌러 작업 화면으로 돌아갑니다.

5실습 폴더 연결하기

ZCode는 내가 고른 폴더 안에서만 파일을 만들고 고칩니다. 그래서 해커톤용 빈 폴더를 먼저 만들어 두는 것이 좋습니다. 예를 들어 바탕화면에 해커톤 폴더를 만듭니다. 개인 문서나 다른 과제가 들어 있는 폴더는 고르지 않습니다.

1. ①작업 화면 가운데 입력창 위의 Select project를 누릅니다.
2. ②목록 아래쪽의 Create project를 누릅니다.

1. ①Project name에 알아보기 쉬운 이름을 넣습니다. 그림에서는 해커톤-실습으로 지었습니다.
2. ②Source folders의 Choose folder를 눌러 앞에서 만든 빈 폴더를 고르고 확인 버튼(macOS는 Open)을 누릅니다. 폴더를 고르면 Choose folder 자리에 폴더 이름이 표시됩니다.
3. ③Create project를 누릅니다.

1. ④'Trust this folder?' 창이 뜹니다. ZCode가 이 폴더의 파일을 읽고 고쳐도 되는지 묻는 창입니다. 표시된 경로가 내가 만든 실습 폴더가 맞는지 확인하고 Trust folders and create를 누릅니다.

6모델과 작업 방식 고르기

입력창 오른쪽 아래의 모델 버튼에서 서울라우트 모델을 고릅니다.

1. ①입력창 오른쪽 아래의 모델 버튼을 누릅니다. 버튼에는 지금 골라진 모델 이름이나 'Choose model'이 보입니다.
2. ②열린 메뉴 맨 위 줄이 서울라우트 API인지 확인합니다.
3. ③Models 목록에서 쓸 모델을 고릅니다. 처음에는 기본 추천인 glm-5.3을 고릅니다.

맨 위 줄에 다른 이름이 보이면 그 줄을 누릅니다. 오른쪽에 공급자 목록이 펼쳐지면 서울라우트 API를 고릅니다. 계정을 연결하지 않았다면 이 목록에는 직접 만든 공급자만 나옵니다.

메뉴 아래쪽의 Effort는 AI가 답하기 전에 얼마나 깊이 생각할지 정하는 추론 수준입니다. 처음 값 그대로 둡니다. 행사 전 시험도 처음 값으로 했습니다.

다음으로 ZCode가 파일을 고칠 때 얼마나 물어볼지 정합니다.

1. ①입력창 왼쪽 아래의 작업 방식 버튼을 누릅니다.
2. ②Ask before changes(바꾸기 전에 묻기)를 고릅니다. 처음 쓰는 사람에게 권하는 방식입니다.

7첫 작업으로 연결 확인하기

AI가 답만 하는 것이 아니라 실제로 파일을 만들 수 있는지 확인합니다. 아래 문장을 복사해 입력창에 붙여넣습니다.

1. ①입력창 오른쪽 끝의 화살표(보내기) 버튼을 누릅니다. Return(Windows는 Enter)을 눌러도 됩니다.

AI가 잠시 생각한 뒤 파일을 쓰려고 하면 'Permission required'(허락 필요) 상자가 나옵니다. Ask before changes를 골랐기 때문입니다.

1. ①Allow(이번만 허락)를 고릅니다.
2. ②Confirm을 누릅니다.

잠시 뒤 '완료했습니다'와 함께 '1 file changed'가 보이면 연결이 끝난 것입니다. 실습 폴더를 Finder(Windows는 파일 탐색기)로 열어 connection-check.txt 파일이 생겼는지도 직접 확인합니다.

8문제가 생겼을 때

서울라우트는 문제가 생기면 한국어 안내 문구를 돌려줍니다. ZCode에서는 대화창 아래쪽에 회색 오류 막대로 보입니다. 오류 막대의 ① Copy를 누르면 문구를 복사할 수 있습니다.

오류 문구에 따라 아래 표의 할 일을 따라 합니다.

9키를 안전하게 쓰는 법

• 키는 본인만 씁니다. 팀원에게도 보내지 않습니다. 메신저, 깃허브, 발표 자료, 화면 캡처에 키가 나오지 않게 합니다.
• 공공데이터포털 인증키와 다릅니다. 공공데이터포털 인증키는 데이터를 받아 오는 열쇠이고, 서울라우트 키는 AI 모델을 부르는 열쇠입니다. 서로 바꿔 넣지 않습니다.
• 웹 앱에서는 서버 비밀 설정에만 넣습니다. 만든 웹 앱에서 AI를 부를 때는 키를 서버 쪽 비밀 설정(Secrets)에만 넣습니다. 브라우저에서 실행되는 코드나 VITE_로 시작하는 환경 변수에 넣으면 누구나 키를 볼 수 있습니다.
• 공용 PC는 사용 뒤 창을 닫습니다. 개인 페이지 창을 닫고, ZCode의 Model settings에서 서울라우트 공급자를 … → Delete로 지웁니다. ZCode 계정에서 로그아웃해도 직접 만든 공급자와 저장한 키는 그대로 남기 때문에 공급자를 꼭 지워야 합니다.
• 키가 새어 나갔다고 생각되면 바로 운영진에게 참가 번호를 알려 주세요.