준비물
채팅으로 프로젝트를 만들기 전에 갖출 것 — AI 공급자 API 키, cob 와 bricks, 명령줄 도구, 비공개 저장소 읽기 권한.
목차
앱을 설치하는 것만으로는 채팅으로 프로젝트를 만들 수 없습니다. 아래 네 가지가 갖춰져야 「조립 계획」을 세우고 프로젝트를 만들 수 있습니다.
| 준비물 | 무엇에 쓰나요 | 앱에서 확인하는 곳 |
|---|---|---|
| AI 공급자 API 키 | 조립 계획을 한국어로 설명하는 AI 모델을 부릅니다 | 설정 › AI 공급자 |
| cob 와 bricks | 프로젝트를 실제로 조립합니다 | 설정 › 빌더 |
| 명령줄 도구 | cob 가 프로젝트를 만들고 검증하고 게시하는 데 씁니다 | 터미널에서 <명령> --version |
| 비공개 저장소 읽기 권한 | cob · bricks · 생성된 프로젝트의 의존 패키지를 내려받습니다 | 터미널의 git 이 GitHub 에 인증된 상태 |
주의
2026-10-08 기준, cob 설치와 의존 패키지 내려받기에는 비공개 GitHub 저장소를 읽을 권한이 필요합니다. 설치 파일은 (이 문서를 확인한 날에는) 누구나 내려받을 수 있었지만, 그 권한이 없으면 cob 를 설치하지 못하고 채팅으로 프로젝트를 만들 수 없습니다. 권한을 받는 방법은 이 문서가 다루지 않습니다.
설정 화면은 사이드바 맨 아래의 톱니바퀴 「설정」 단추로 엽니다. 화면별 설명은 설정에 있습니다.
AI 공급자 API 키
Cocode IDE 는 모델 사용료를 대신 내 주지 않습니다. 쓰려는 공급자의 API 키를 직접 준비해 넣는 방식(BYOK, Bring Your Own Key)이고, 사용료는 그 공급자에게 직접 냅니다. 지원하는 공급자는 아홉 가지입니다.
| 공급자 | API 키 | 키를 읽는 환경 변수 |
|---|---|---|
| OpenAI | 필요 | OPENAI_API_KEY |
| Anthropic | 필요 | ANTHROPIC_API_KEY |
| Google Gemini | 필요 | GEMINI_API_KEY, 없으면 GOOGLE_API_KEY |
| OpenRouter | 필요 | OPENROUTER_API_KEY |
| xAI | 필요 | XAI_API_KEY |
| DeepSeek | 필요 | DEEPSEEK_API_KEY |
| Groq | 필요 | GROQ_API_KEY |
| Ollama (내 컴퓨터에서 도는 모델) | 필요 없음 | — |
| 사용자 지정 OpenAI-compatible | 필요 | OPENAI_COMPATIBLE_API_KEY |
Ollama 와 사용자 지정 공급자는 모델 ID 를 직접 넣어야 합니다. 비어 있으면 채팅이 「… 모델이 설정되지 않았습니다」라고 알립니다. 사용자 지정은 「API base URL」도 적용해야 합니다. 다른 공급자는 비워 두면 기본 모델을 씁니다.
키를 넣는 방법은 두 가지입니다.
- 설정에서 저장합니다. 「설정」 › 「AI 공급자」에서 공급자 카드를 고르고 「API 키」 칸에 키를 넣어 「저장」을 누릅니다. 설정 화면의 설명대로 키는 OS 키체인에만 저장되고 화면 · 로그 · 저장소에 남지 않습니다. 저장소는 macOS 는 Keychain, Windows 는 자격 증명 관리자, Linux 는 Secret Service 이고, Linux 에서는
secret-tool명령(Debian · Ubuntu 는 libsecret-tools 패키지)이 있어야 합니다. - 환경 변수로 줍니다. 위 표의 환경 변수를 Cocode IDE 앱 프로세스가 가지고 있으면 그 키를 읽습니다. 키체인에도 키가 있으면 키체인 값이 우선합니다. 환경 변수 키는
OPENAI_BASE_URL처럼 공급자마다 정해진…_BASE_URL환경 변수가 없으면 그 공급자의 공식 주소로 연결할 때만 쓰이고, 그 변수가 있으면 연결 주소와 같을 때만 쓰입니다(다르면 공식 주소에서도 무시됩니다). 사용자 지정 공급자는OPENAI_COMPATIBLE_BASE_URL이 항상 필요합니다.
공급자 카드에는 키의 출처가 「키체인에 저장됨」 · 「환경 변수 …」 · 「키 없음」으로 보이고, 키가 있는 공급자 중 하나가 기본으로 쓰입니다. 공급자를 여럿 쓰면 카드를 눌러 「기본으로 설정」으로 고르세요. 화면 전체는 AI 공급자에 있습니다.
주의
Linux 에서는 설정의 「저장」이 실패할 수 있습니다(2026-10-08 기준 0.1.0 과 개발 브랜치 소스). 앱이 secret-tool 을 부를 때 데스크톱 세션의 D-Bus 환경 변수(DBUS_SESSION_BUS_ADDRESS · XDG_RUNTIME_DIR · DISPLAY)를 넘기지 않아서, secret-tool 과 키 보관 데몬(gnome-keyring · KWallet 같은 것)이 있어도 「키를 저장하지 못했습니다 — 키 저장소를 확인하세요」가 나올 수 있습니다. Linux 에서는 환경 변수로 키를 주는 방법을 쓰세요.
참고
Linux 에서 secret-tool 명령이 없으면 설정 화면이 「이 기기에서는 OS 키 저장소를 쓸 수 없습니다」라고 알리고 환경 변수로 키를 주라고 안내합니다. 키를 평문 파일로 저장하는 대체 경로는 없습니다.
키가 없는 채로 요구를 보내면 채팅에 「빌더가 멈췄습니다」 카드가 나타나고 「<공급자> API 키가 없습니다. 설정 › AI 공급자에서 키를 저장하거나 <환경 변수> 를 설정하세요.」라고 알립니다. 카드의 「설정 열기」 단추가 설정 화면으로 데려갑니다.
설정에는 「Jev 키」도 있지만 선택 사항입니다. 키가 없어도 빌더는 멈추지 않고 카탈로그 일치 규칙으로 판단합니다.
cob 와 bricks
Cocode IDE 는 프로젝트를 직접 만들지 않고 cob 라는 명령줄 도구를 불러 조립합니다. cob 는 bricks(미리 만들어 둔 코드 조각 모음)를 이 컴퓨터에 내려받아 두고, 그 카탈로그에서 레시피와 브릭을 고릅니다. 앱은 홈 폴더 아래 .cob/bricks 에 그 체크아웃이 있는지 확인합니다(Windows 에서 cob 가 실제로 받는 위치는 확인하지 못했습니다).
「설정」 › 「빌더」는 아래 네 가지를 한 번에 보여 줍니다. 항목을 열 때 한 번, 「다시 확인」을 누를 때마다 다시 확인하고, 이 확인은 아무것도 바꾸지 않습니다. 자세한 화면 설명은 빌더에 있습니다.
| 항목 | 정상일 때 | 문제가 있을 때 |
|---|---|---|
| cob 실행 파일 | cob 와 버전 |
「PATH 에서 찾지 못했습니다」 |
| 빌더 기계 API | 「plan --spec 지원」 | 「plan --spec 이전 버전입니다 — 갱신이 필요합니다」 |
| bricks 체크아웃 | .cob/bricks 경로(macOS · Linux 는 ~/.cob/bricks 로 줄여 보입니다) |
이 폴더가 없다는 안내 |
| 레시피 카탈로그 | 「레시피 목록을 찾았습니다」 | 「레시피 목록을 찾지 못했습니다 — cob 갱신이 필요합니다」 |
문제가 있으면 같은 화면 아래에 할 일이 나옵니다.
- cob 를 설치(또는 갱신)합니다. 「cob 를 설치하세요」 · 「cob 를 갱신하세요」 안내 아래에 터미널 명령이 보입니다. 「복사」 단추로 복사해 터미널에 붙여 넣어 실행하고, 설정에서 「다시 확인」을 누릅니다. 이 명령에는 앱 버전에 맞춘 cob 버전이 박혀 있으니 직접 치지 말고 앱이 보여 주는 것을 쓰세요.
- bricks 를 받습니다. 「bricks 체크아웃이 없습니다」가 보이면, 채팅에서 계획을 만들 때 나오는 「bricks 받기」 단추가 홈 폴더 아래
.cob/bricks로 내려받습니다(Windows 는 위의 단서를 보세요). 터미널에서 받으려면cob doctor --fix를 실행합니다.
명령줄 도구
앱이 직접 부르거나 cob 가 부르는 도구는 모두 PATH 에서 찾을 수 있어야 합니다. 터미널에서 <명령> --version 이 동작하는지 확인해 보세요. cob 를 설치하는 명령은 Dart 3.13 이상이 있어야 하고, 이 앱은 Flutter 3.47.6(Dart 3.13.5)으로 빌드됐습니다.
| 도구 | 쓰이는 곳 |
|---|---|
git |
「URL에서 복제」, 새 프로젝트의 「git 저장소로 초기화」, bricks 내려받기 |
gh (GitHub CLI) |
앱이 안내하는 cob 버전의 사전 점검이 로그인 여부를 확인하고, 로그인되어 있지 않으면 거기서 멈춥니다. Pages 를 켜면 저장소 이름 확인과 게시에도 씁니다 |
dart · flutter · melos |
cob 가 프로젝트를 만들고 검증하는 도구입니다 |
코드 모드의 「실행」과 「프리뷰」는 열려 있는 프로젝트의 종류에 따라 flutter · dart(Jaspr 웹은 dart run jaspr_cli:jaspr serve)와 서버 실행 도구(serverpod start, 또는 프로젝트의 tool/serverpod/cli.sh 를 bash 로)를 부르고, FVM 을 쓰는 프로젝트는 flutter · dart 앞에 fvm 을 붙입니다. 도구를 찾지 못하면 앱이 「<명령> 명령을 PATH 에서 찾지 못해 실행하지 않았습니다」라고 알립니다.
macOS · Linux 에서는 Dock · Finder 같은 곳에서 앱을 열어도, 시작할 때 로그인 셸($SHELL -l -i)의 PATH 를 한 번 읽어 옵니다. 5초 안에 끝나지 않으면 앱이 받은 PATH 를 그대로 씁니다. Windows 에서는 앱이 시작된 환경의 PATH 를 씁니다.
비공개 저장소 읽기 권한
cob 를 설치하는 명령이 받아 오는 저장소, bricks 체크아웃, 그리고 생성되는 프로젝트가 의존하는 CoUI 패키지는 모두 비공개 GitHub 저장소에 있습니다(2026-10-08 확인). 그래서 터미널의 git 이 그 저장소를 읽을 수 있는 GitHub 계정의 자격 증명으로 동작해야 합니다. 권한이 없으면 cob 설치, 「bricks 받기」, 프로젝트의 의존 패키지 내려받기가 실패합니다.
확인
- 「설정」 › 「AI 공급자」: 쓰려는 공급자 카드에 「키체인에 저장됨」이나 「환경 변수 …」가 보입니다.
- 「설정」 › 「빌더」: 네 항목이 모두 정상으로 보입니다.
- 터미널:
git --version·gh auth status·dart --version·flutter --version·melos --version이 모두 동작합니다.
자주 겪는 문제
「cob 실행 파일을 찾지 못했습니다」가 보입니다
cob 가 설치되어 있지 않거나 PATH 에 없습니다. 「설정」 › 「빌더」의 설치 명령을 실행한 뒤 「다시 확인」을 누르세요. 설치했는데도 찾지 못하면 터미널에서 cob --version 이 동작하는지 확인하세요. dart pub global 로 설치한 실행 파일은 macOS · Linux 에서는 $HOME/.pub-cache/bin, Windows 에서는 %LOCALAPPDATA%\Pub\Cache\bin 에 놓이고, 그 폴더가 PATH 에 들어 있어야 합니다(dart pub global).
「cob 갱신이 필요합니다」가 보입니다
설치된 cob 가 빌더가 쓰는 plan --spec 이전 버전입니다. 「설정」 › 「빌더」의 「cob 를 갱신하세요」 아래 명령을 실행한 뒤 「다시 확인」을 누르세요.
「레시피 카탈로그를 찾지 못했습니다」가 보입니다
cob 가 레시피를 한 건도 돌려주지 않아 계획을 만들 수 없는 상태입니다. cob 를 갱신하고 다시 확인하세요. bricks 체크아웃이 없는 경우는 먼저 「bricks 받기」(또는 cob doctor --fix)로 받아 두세요.
「이 기기에서는 OS 키 저장소를 쓸 수 없습니다」가 보입니다
Linux 에서 secret-tool 명령(Debian · Ubuntu 는 libsecret-tools 패키지)을 찾지 못한 경우입니다. 패키지를 설치해도 위 경고 때문에 「저장」이 실패할 수 있으니 위 표의 환경 변수로 키를 주세요. 환경 변수는 Cocode IDE 앱 프로세스가 가지고 있어야 읽힙니다.
다음 단계
준비가 되면 설치 파일을 받습니다. 설치로 이어서 진행하세요.