AI/Open Models

Ollama Launch 사용 방법(ollama 사용방법) : Claude Code, OpenCode, Codex App을 Ollama 모델로 실행 해보기

Q: ollama launch를 쳤는데 통합이 몇 개 안 보인다. 지원이 안 되는 건가?

데스크톱 앱 카드는 자주 쓰는 것만 선별해 보여준다. 전체 지원 목록은 터미널에서 ollama launch --help로 확인한다. 직접 테스트 기준 16개가 나열되며, 카드에 없어도 ollama launch 으로 실행되는 경우가 많다.

Q: 로컬 모델이 자꾸 느리거나 메모리 부족으로 죽는다.

로컬 대형 모델은 VRAM을 많이 요구한다. 예로 glm-4.7-flash는 64000 토큰 컨텍스트에서 약 23GB VRAM이 필요하다. 하드웨어가 못 따라가면 같은 계열의 :cloud 모델로 바꾼다. 모델 이름만 바꾸면 되고, 클라우드는 로컬 사양과 무관하게 전체 컨텍스트 길이를 쓴다.

Q: Codex App을 연결했더니 앱이 안 열린다.

Codex를 수동으로 한 번 연 뒤 ollama launch codex-app을 다시 실행한다. 이미 실행 중인데 모델이 안 바뀌면 Ollama가 재시작을 물어볼 때 허용하거나 앱을 종료한 뒤 다시 실행한다. 원 설정으로 돌리고 싶으면 --restore를 쓴다.

안녕하세요! 갓대희 입니다.

Ollama를 "내 컴퓨터에서만 도는 로컬 모델 도구"로 알고 있는 사람이 아직 많다.

"Claude Code는 이 모델, Codex는 저 모델"처럼 에이전트마다 쓸 수 있는 모델이 따로 정해져 있다고 생각하는 사람도 있다.

예전에는 Ollama·LM Studio·vLLM·LiteLLM을 손으로 하나씩 붙이는 글을 따로 써야 했을 만큼 이 두 생각이 어느 정도는 맞았다. 그런데 지금은 둘 다 맞지 않는 것 같다.

ollama launch는 Claude Code·Codex App·OpenCode 같은 코딩 도구를 로컬 모델이든 클라우드 모델이든 한 줄 명령으로 연결해 준다고 한다.

환경변수를 손으로 넣거나 설정 파일을 만질 필요가 없다.

이에 직접 해보려고 한다.(2026년 7월 초 시점이고, macOS, Ollama 0.30.11 기준으로 테스트 해볼 예정이다).

ollama launch --help를 확인 해 보니 지원 통합이 16개나 나열되어 있다.

GUI로 확인해도 유사하다.

이 글에서는 ollama launch가 무엇인지, 어떻게 16개 에이전트로 늘어났는지, 로컬 모델과 클라우드 모델(:cloud 접미사)을 어떻게 구분해 쓰는지 직접 확인한 대로 짚어본다. 이어서 Claude Code·Codex App·OpenCode 세 도구는 그대로 따라 할 수 있게 실습하고, 나머지 에이전트는 개요와 공식 문서 링크를 남겨 놓는 정도로 진행해보려 한다.

이 글의 핵심 6가지

ollama launch 한 줄이면 코딩 에이전트에 환경변수·설정 파일 없이 모델을 연결한다
로컬 모델과 클라우드 모델(:cloud)을 모두 지원한다 — "로컬 전용"이 아니다
직접 테스트 기준 ollama launch --help가 지원하는 통합은 16개다
데스크톱 앱 카드(약 8개)와 CLI(16개)의 숫자가 다른 이유가 있다
에이전트와 모델은 고정이 아니라 --model로 자유롭게 바꾼다
OpenClaw 웹서치처럼 ollama signin 계정 로그인이 필요한 기능이 있다

Ollama Launch란 무엇인가
연혁 — Anthropic API 호환에서 16개까지
로컬 모델 vs 클라우드 모델 (:cloud)
앱 카드 8개와 CLI 16개, 왜 다른가
사전 준비 — 버전·컨텍스트 길이
실습 ① Claude Code
실습 ② Codex App
실습 ③ OpenCode
--model 플래그 — 매핑은 고정이 아니다
나머지 에이전트 한눈에 보기
계정 로그인이 필요한 기능 (ollama signin)
트러블슈팅 & Q&A
마무리 — 로컬과 클라우드, 무엇을 고를까

먼저 용어부터 가볍게 잡고 가자

Ollama Launch: ollama launch 한 줄로 코딩 도구를 Ollama 모델에 연결하는 명령
통합(integration): Ollama가 연결을 지원하는 외부 앱·에이전트
로컬 모델: 내 컴퓨터의 VRAM(그래픽 메모리)에서 직접 돌리는 모델
클라우드 모델(:cloud): Ollama 서버에서 돌아가는 모델, 이름 끝에 :cloud가 붙는다
코딩 에이전트: 코드를 읽고 편집·실행까지 하는 AI 도구 (Claude Code·Codex 등)
컨텍스트 길이: 모델이 한 번에 다루는 토큰 수 — 클수록 큰 코드베이스를 담는다
ANTHROPIC_BASE_URL: Claude Code가 요청을 보낼 주소를 바꾸는 환경변수
ollama signin: Ollama 계정에 로그인하는 CLI 명령

1. Ollama Launch란 무엇인가

ollama launch는 좋아하는 코딩 도구를 로컬 또는 클라우드 모델로 설정하고 실행하는 새 명령이다. 공식 블로그는 이 명령을 소개하며 "환경변수나 설정 파일이 필요 없다(No environment variables or config files needed)"라고 못 박는다.

ollama launch is a new command which sets up and runs your favorite coding tools like Claude Code, OpenCode, and Codex with local or cloud models.
(ollama launch는 Claude Code, OpenCode, Codex 같은 AI 코딩 도구를 로컬 또는 클라우드 모델과 연동해 손쉽게 설정하고 실행할 수 있는 새로운 명령어입니다.)

인용문의 마지막 구절이 이 글 전체의 전제다. 정의부터 "로컬 또는 클라우드 모델(local or cloud models)"이라고 적혀 있으니, "Ollama는 로컬 전용"이라는 흔한 요약은 이 명령 앞에서는 성립하지 않는다.

공식 CLI 문서는 이 명령을 조금 더 기계적으로 설명한다. 지원 앱과의 통합을 설정하고 시작하는 대화형(interactive) 방식을 제공한다는 것이다.

ex) ollama launch (내가 돌렸을때는 실제로 다음과 같이 나온다.)

공식 문서의 화면을 보면 ollama launch만 입력했을 때 claude·codex·droid·opencode 네 항목이 뜨고, 각 항목에 기본 모델(glm-4.7-flash:latest 등)이 미리 매핑돼 있다. 대화형이라는 말은 이렇게 목록에서 하나를 고르면 나머지 설정을 Ollama가 알아서 채운다는 말이다. (물론 내 로컬에선 공식문서와 달랐지만, 일단 공식 문서 기준으로 진행해보자. )

이 명령의 핵심은 결국 "설정 자동화"다. 예전에는 각 도구마다 어떤 환경변수를 어디에 넣어야 하는지 문서를 일일이 뒤져야 했는데, 그 과정을 명령 한 줄로 접은 것이 이 명령의 등장 배경이다.

왜 이게 편할까

설정 파일을 직접 여는 방식은 오타 하나로 연결이 깨지기 쉽다. 환경변수를 손으로 넣다가 어딘가에서 막혀본 사람이라면 이 번거로움에 공감할 것이다.

ollama launch는 검증된 설정을 도구별로 넣어 주므로, 처음 붙여 보는 단계에서 그렇게 막힐 확률이 줄어든다.

익숙해지면 수동 설정으로 넘어가도 되지만, 첫 연결은 이 명령으로 시작하는 편이 낫다.

2. 연혁 — Anthropic API 호환에서 16개까지

이 기능은 갑자기 튀어나온 게 아니라 여러 버전에 걸쳐 쌓였다.

날짜만 보면 헷갈리기 쉬우니, 버전 번호를 기준으로 따라가면 정확하다.

먼저 토대가 된 사건은 Ollama v0.14.0의 Anthropic Messages API 호환이다. 이 버전부터 Claude Code 같은 도구를 오픈소스 모델과 함께 쓸 수 있게 됐다고 공식 블로그에서 밝히고 있다.

GitHub v0.14.0 릴리스 노트에도 Anthropic API 호환(/v1/messages API 지원)이 변경사항으로 올라 있다. (출처: GitHub 릴리스 v0.14.0)

ollama launch 명령 자체는 v0.15.0에서 Claude Code·Codex·OpenCode·Droid 네 개 통합으로 처음 도입됐다.

(출처: GitHub 릴리스 v0.15.0) 이후 통합이 하나씩 붙었다.

버전	시점	추가·변경된 것
v0.14.0	2026-01	Anthropic Messages API 호환 — Claude Code를 오픈소스 모델과 연결
v0.15.0	2026-01	`ollama launch` 최초 도입 — Claude Code·Codex·OpenCode·Droid 4개
v0.15.2	2026-01-27	OpenClaw(당시 이름 Clawdbot) 추가
v0.15.3	2026-02-01	`clawdbot` → `openclaw`로 명령 이름 변경
v0.21.0	2026-04-17	Hermes·GitHub Copilot CLI 2개 추가
v0.24.0	2026-05-14	Codex App 추가 (데스크톱 앱)
0.30.11	2026-07-02 확인	직접 테스트 기준 `--help` 통합 16개

여기서 나도 처음에는 잘못 알고 있었다.

릴리스 히스토리를 훑기 전까지는 OpenClaw가 v0.21.0에서 새로 추가된 통합이라고 생각했다.

그런데 직접 하나씩 태그를 열어보니 순서가 달랐다.

실제로는 'Clawdbot'이라는 이름으로 v0.15.2에 먼저 들어왔고, 다음 릴리스에서 이름만 openclaw로 바뀐 것이었다.

그러면 v0.21.0에서는 정작 뭐가 새로 붙었을까 싶어 그 릴리스 노트도 확인해봤는데, Hermes와 GitHub Copilot CLI 두 개만 신규로 명시돼 있고 OpenClaw 관련 항목은 --yes 플래그 버그 수정뿐이었다.

참고로 직접 테스트한 ollama launch --help에도 openclaw의 별칭으로 clawdbot·moltbot이 남아 있어서, 옛 이름이 하위호환으로 유지되는 점도 확인했다.

데스크톱 앱을 겨냥한 Codex App은 조금 뒤인 v0.24.0에서 추가됐다.

릴리스 노트는 "Ollama 0.24 includes support for the Codex App"이라고 적는다. 뒤에서 다루겠지만 Codex App 실습에는 이 최소 버전(v0.24.0+)이 그대로 요구사항이 된다.

넉 달 남짓한 기간에 4개에서 16개로 늘어난 셈이다. 확장 방향을 보면 단순히 개수만 늘어난 게 아니라, 터미널 CLI(Claude Code·Codex·OpenCode)에서 데스크톱 앱(Codex App·Hermes Desktop), 그리고 메시징 어시스턴트(OpenClaw)까지 도구의 성격이 넓어졌다. 코딩 에이전트 생태계가 특정 벤더에 묶이지 않고 "모델은 갈아 끼우는 것"이라는 쪽으로 움직이고 있다.

넉 달 만에 4배

2026년 1월 v0.15.0의 4개 통합(Claude Code·Codex·OpenCode·Droid)에서 직접 테스트 기준 16개까지, 넉 달 남짓 만에 4배로 늘었다. 이 속도라면 지금 목록에 없는 도구가 다음 버전에 추가돼도 이상하지 않다.

3. 로컬 모델 vs 클라우드 모델 (:cloud)

ollama launch를 제대로 쓰려면 로컬 모델과 클라우드 모델의 차이를 먼저 구분해야 한다.

다행히 둘의 구분은 의외로 단순하다. 모델 이름 끝에 :cloud가 붙으면 클라우드, 없으면 로컬이다. 공식 블로그의 예시를 보면 이 구분이 한눈에 들어오는데, 같은 계열 모델을 로컬로 받을 수도 클라우드로 받을 수도 있다.

# 로컬: 64000 토큰 컨텍스트 기준 약 23GB VRAM 필요
ollama pull glm-4.7-flash

# 클라우드: 전체 컨텍스트 길이 지원 (:cloud 접미사)
ollama pull glm-4.7:cloud

주석에 적힌 그대로, 로컬 glm-4.7-flash는 64000 토큰 컨텍스트에서 약 23GB의 VRAM을 요구한다.

웬만한 노트북 그래픽카드로는 부담스러운 크기다. 반대로 :cloud 모델은 연산이 Ollama 서버에서 이뤄지므로 내 VRAM과 무관하게 전체 컨텍스트 길이를 쓴다.

구분	로컬 모델	클라우드 모델 (:cloud)
이름 예시	`glm-4.7-flash`, `gpt-oss:20b`	`glm-4.7:cloud`, `qwen3-coder:480b-cloud`
연산 위치	내 컴퓨터(VRAM)	Ollama 서버
하드웨어 부담	VRAM 요구(예: 약 23GB)	로컬 사양과 무관
컨텍스트 길이	VRAM에 따라 제한	전체 컨텍스트 길이
계정 로그인	불필요	Ollama 계정 필요(클라우드 서비스)
오프라인	가능	불가(네트워크 필요)

표의 핵심은 간단하다.

로컬은 하드웨어를 갈아 넣어 프라이버시와 오프라인을 얻고, 클라우드는 하드웨어 부담 없이 큰 컨텍스트를 빌려 쓰는 구조다.

로컬로 큰 모델을 돌리기 어렵다면 클라우드가 대안이라고 공식 블로그도 안내한다. ( 개인 노트북을 사용하시는 분들은 현실적으로 큰 모델 돌리기가 어렵다. )

무료 티어에서도 전체 컨텍스트 길이와 넉넉한 한도를 제공한다고 한다.

VRAM이 부족할 때

약 23GB VRAM은 개인 데스크톱에서도 상급 GPU가 있어야 나오는 수치다.

로컬 실행이 자꾸 느리거나 메모리 부족으로 죽는다면, 무리해서 로컬 대형 모델을 붙들기보다 같은 계열의 :cloud 모델로 갈아타는 편이 낫다. 코드는 그대로 두고 모델 이름만 바꾸면 된다.

어느 쪽부터 시작할까

개인적으로는 처음이라면 :cloud 모델로 동작을 먼저 확인하고, 프라이버시가 중요하거나 자주 쓰는 작업이 정해지면 그때 로컬로 내려오는 순서를 권한다.

로컬 설치·다운로드 시간에 막혀 "연결 자체가 되는지"조차 확인하지 못하는 상황을 줄일 수 있어서다.

4. 앱 카드 8개와 CLI 16개, 왜 다른가

Ollama를 데스크톱 앱으로 쓰는 사람은 앱의 'Launch' 탭에서 카드 형태로 통합을 고른다.

그런데 이 카드 개수와 CLI가 지원하는 개수는 계속 업데이트 됨에 따라 늘어나고 있다.

현재 내가 직접 테스트(2026년 7월 2일, macOS, Ollama 0.30.11)에서 확인한 ollama launch --help의 지원 통합은 16개였다.

Supported integrations:
  claude          Claude Code
  codex-app       Codex App (aliases: codex-desktop, codex-gui)
  hermes          Hermes Agent
  openclaw        OpenClaw (aliases: clawdbot, moltbot)
  opencode        OpenCode
  codex           Codex
  hermes-desktop  Hermes Desktop
  copilot         Copilot CLI (aliases: copilot-cli)
  omp             OMP
  droid           Droid
  kimi            Kimi Code CLI
  pi              Pi
  pool            Pool
  cline           Cline
  qwen            Qwen Code
  vscode          VS Code (aliases: code)

데스크톱 앱의 'Launch' 탭에는 자주 쓰는 코딩 에이전트만 카드로 노출된다.

직접 확인한 앱 화면(2026-07-02 기준)에는 총 8개 밖에 노출 안되고 있다.

(Claude Code·Codex App·Hermes Agent·OpenClaw·OpenCode·Codex·Copilot CLI·Droid)

"Copy a command and run it in your terminal(명령을 복사해 터미널에서 실행하라)"이라는 안내가 보였다.

카드가 8개뿐이라 처음엔 "나머지 8개는 어디 갔지" 싶었는데, 앱 카드는 애초에 전체 목록이 아니라 대표 선별본이었다.

그렇다면 공식 문서 사이트의 통합 인덱스는 어떨까 싶어 함께 찾아봤더니 또 다른 숫자가 나온다.

문서 인덱스는 통합을 7개 카테고리로 나눠 총 24개를 나열하는데,

여기에는 에디터 플러그인·자동화·RAG 도구까지 들어가 있어 CLI가 다루는 코딩 에이전트보다 범위가 넓다.

표면	노출 개수	성격
데스크톱 앱 'Launch' 탭	약 8개	자주 쓰는 코딩 에이전트만 선별 (앱 화면 기준)
CLI `ollama launch --help`	16개	실제 `launch`로 설정 가능한 전체 통합
공식 문서 통합 인덱스	24개	에디터·자동화·RAG까지 포함한 문서 전체

세 숫자가 다른 이유는 각 표면의 목적이 다르기 때문이다.

앱 카드는 초심자가 헤매지 않도록 좁혔고, CLI는 실제 지원 범위를 그대로 드러내며, 문서 인덱스는 관련 도구까지 폭넓게 안내한다.

"내 앱에 안 보인다"고 해서 지원되지 않는다고 단정할 필요는 없다.

카드에 없어도 터미널에서 ollama launch <이름>으로 실행되는 경우가 많다.

launch 명령의 4가지 플래그

ollama launch에는 알아두면 자주 쓰는 플래그가 네 개 있다. 직접 테스트한 --help 출력과 공식 블로그를 종합했다.

플래그	하는 일
`--config`	도구를 즉시 실행하지 않고 설정만 한다
`--model`	사용할 모델을 지정한다 (예: `--model glm-4.7:cloud`)
`--restore`	통합을 Ollama 실행 이전의 기본 프로필로 되돌린다
`-y`, `--yes`	확인 프롬프트에 자동으로 예로 답한다 (스크립트·CI용)

이 네 플래그가 뒤의 실습에서 반복해서 등장한다.

특히 --model은 다음 절에서 설명할 "매핑은 고정이 아니다"의 핵심이고,

--restore는 설정을 되돌리는 안전장치라 언제든지 복구하기 쉬우니 맘편히 진행해보자..

넷 중 가장 자주 쓰는 건 --model 하나

실습에서 반복해서 쓰는 건 사실상 --model뿐이다.

--config·--restore·-y는 "설정만 해두고 싶을 때", "원래대로 되돌리고 싶을 때", "자동화 스크립트에서 확인을 건너뛰고 싶을 때"처럼 특정 상황에서만 꺼내면 된다.

넷을 한 번에 외우려 하지 말고 뒤의 실습을 따라가며 하나씩 마주치는 편이 낫다.

5. 사전 준비 — 버전·컨텍스트 길이

실습 전에 두 가지만 확인하면 된다.

Ollama 버전과 컨텍스트 길이 설정이다.

첫째는 버전이다. Ollama Launch는 v0.15+가 필요하다고 공식 블로그가 안내하니, 터미널에서 설치 버전부터 확인하고 시작하자.

# 설치된 Ollama 버전 확인
ollama --version

# 지원 통합과 플래그 확인
ollama launch --help

첫 명령은 설치된 버전을 출력한다.

나의 테스트 환경에서는 ollama version is 0.30.11이다.

두 번째 명령으로는 앞에서 본 16개 통합 목록이 출력돼, 내 환경이 어떤 통합을 지원하는지 바로 확인할 수 있다.

여기서 하나 더 알아두면 좋은 점은, 에이전트에 따라 요구하는 최소 버전이 다르다는 것이다.

대표적으로 Codex App은 Ollama v0.24.0 이상이 필요하다.

둘째는 컨텍스트 길이다. 코딩 도구는 큰 컨텍스트에서 가장 잘 동작하므로, Ollama 설정에서 컨텍스트 길이를 넉넉히 올려야 한다.

다만 권장 하한선이 문서마다 조금씩 다르다.

통합	최소 Ollama 버전	권장 컨텍스트 길이
Claude Code	v0.14.0+ (Anthropic API 호환)	최소 32K 토큰
Codex App	v0.24.0+	(블로그 일반 권장치 적용)
Copilot CLI	v0.21.0+	최소 64k 토큰
공통 권장(코딩 도구)	v0.15+	최소 64000 토큰

표의 마지막 행이 기준선이다.

공식 블로그는 "컨텍스트 길이를 최소 64000 토큰으로 올리라"고 권한다.

Claude Code 문서는 32K를 하한으로 제시하는데, 이는 도구별로 최소 요구가 다를 뿐 값이 클수록 큰 저장소를 다루기 유리하다는 방향은 같다. 처음이라면 64000 토큰을 기준으로 잡고, 리포지토리가 크면 더 올리는 편이 안전하다.

실습 전 체크

Ollama v0.15+ 설치 (ollama --version으로 확인)
Ollama 설정에서 컨텍스트 길이 64000 토큰 이상으로 상향
클라우드 모델(:cloud)을 쓸 거라면 Ollama 계정 로그인(ollama signin)

버전이 낮으면 --help 목록 자체가 짧다

Ollama가 오래된 버전이면 ollama launch --help에 16개가 다 나오지 않는다. 예를 들어 Codex App은 v0.24.0 이상에서만 목록에 뜬다. 원하는 통합이 안 보인다면 지원 종료가 아니라 업데이트가 필요하다는 신호일 수 있다.

6. 실습 ① Claude Code

Claude Code는 이전 글에서 이미 자세히 다뤄본 도구라, 여기서는 핵심 명령과 환경변수만 짚고 넘어간다. 빠른 설정은 한 줄이다.

ollama launch claude

이 명령을 실행하면 Ollama가 Claude Code용 설정을 맞추고 Claude Code를 띄운다.

앞에서 본 것처럼 대화형으로 모델을 고르라는 프롬프트가 나오는데, 아래 화면이 실제로 그 뒤에 이어지는 모습이다.

이제 부터는 실제 공식 문서의 튜토리얼을 진행해보자.

ex) ollama launch claude

내 화면 기준은 ollama launch claude 이후 Claude Code가 glm-5.2:cloud 모델 부터 노출된다.

여기서 곧바로 코드를 물어보면 로컬 모델이 그대로 응답한다.

최근에 glm-5.2에 대해 글을 작성한 적도 있으니, 해당 모델을 선택해보겠다.

클라우드 모델 이용은 무료 계정으로도 가능하지만 사용량 제한이 있다.

무료 계정은 경량 모델 위주의 제한된 GPU 시간을 제공하며 동시에 클라우드 모델 1개만 구동할 수 있다.

위에서 시도한 glm-5.2:cloud처럼 대형 모델은 Pro 구독($20/월) 이상에서 이용 가능하다.

Pro는 무료 대비 50배 사용량에 동시 3개 모델을 지원한다. (출처: ollama.com/pricing, 2026-07-07 직접 확인)

일단 컨셉 증명을 해야 하는거니 클라우드 대신 로컬 모델로 먼저 연결을 확인해보자.

이미 qwen3:8b를 다운로드해 뒀다면 아래 한 줄이면 충분하다.

ollama launch claude --model qwen3:8b

저사양 PC용 로컬 모델 다운로드 (RAM 8 GB 기준)

qwen3:8b가 아직 없거나 더 가벼운 모델이 필요하면 아래 중 하나를 받으면 된다. 크기는 2026-07-07 기준 ollama.com/library에서 직접 확인한 수치다.

모델	다운로드 크기	컨텍스트	특징
`phi4-mini`	2.5 GB	128K	CPU만 있어도 동작, 최경량
`gemma3:4b`	3.3 GB	128K	추론·코드 균형
`qwen2.5-coder:7b`	4.7 GB	128K	코딩 특화, 7B급 최선택
`qwen3:8b`	5.2 GB	40K	범용 성능 우수, 위에서 시도한 모델

⚠️ qwen3-coder는 저사양 PC에 맞지 않는다
qwen3-coder 시리즈의 최솟값은 30b(약 19 GB)다. 이름이 비슷한 qwen3:8b와 다른 시리즈이므로 혼동하지 말자.
(출처: ollama.com/library/qwen3-coder/tags, 2026-07-07 확인)

# 하나만 골라서 받으면 된다
ollama pull phi4-mini          # 2.5 GB — 최경량
ollama pull gemma3:4b          # 3.3 GB
ollama pull qwen2.5-coder:7b   # 4.7 GB — 코딩 특화
ollama pull qwen3:8b           # 5.2 GB — 이미 있으면 skip

ex) ollama launch claude --model qwen3:8b

- 위 예시로 진행해도 되지만, 난 직접 ollama launch claude 를 통해 설정해보겠다.

>> ollama launch claude

>> qwen3:8b 모델로 클로드 코드가 연동 되었다.

- status line도 변경 되어 있다.

- token output 속도가 sonnet4.6일때보다 현저히 느리지만, 일단 정상동작하는 부분. 그리고 코드 수정도 가능하다.

(너무 느려 따로 캡쳐하진 않았다.)

- 소넷 예시

수동으로 붙이고 싶다면 환경변수 세 개를 지정한다. 공식 문서 기준이다.

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

핵심은 ANTHROPIC_BASE_URL을 로컬 Ollama 주소(http://localhost:11434)로 돌려놓는 것이다.

쉽게 말해 Claude Code가 원래 Anthropic 서버로 보내던 요청을 내 컴퓨터의 Ollama로 우회시키는 설정이다. ANTHROPIC_API_KEY=""처럼 빈 값으로 두는 것도 문서가 명시한 그대로다.

모델 지정은 실행할 때 붙인다. 로컬이면 claude --model gpt-oss:20b, 클라우드면 claude --model glm-4.7:cloud 식이다.

# 로컬 모델로 실행
claude --model gpt-oss:20b

# 클라우드 모델로 실행
claude --model glm-4.7:cloud

ex) 이번엔 claude --model glm-4.7:cloud 을 통해 cloud 모델을 사용해보자. ( glm-5.2는 프로 구독이 필요하여 패스 )

- glm4.7:cloud 모델도 정상적으로 기동되는모습

스크립트나 Docker·CI처럼 사람이 지켜보지 않는 환경에서는 --yes를 쓴다. --yes는 선택 프롬프트를 건너뛰고 필요 시 모델을 자동으로 받으며, --model 지정을 반드시 요구한다. -- 뒤에 붙인 인자는 Claude Code에 그대로 전달된다.

ollama launch claude --model gemma4:cloud --yes -- -p "how does this repository work?"

이 명령은 확인 프롬프트 없이 gemma4:cloud 모델로 Claude Code를 띄우고, -p 뒤 질문을 그대로 실행한다. 자동화 파이프라인에 코드 리뷰나 요약을 걸어 둘 때 쓸 만하다.

Claude Code 권장 모델, 어디서 봐야 하나

2026-07-02 기준 Claude Code용 코딩 추천 모델은 로컬 gpt-oss:20b·qwen3-coder, 클라우드 glm-4.7:cloud·minimax-m2.1:cloud다. (출처: Ollama 블로그 — Claude Code)

여기서 하나 짚고 넘어가자면, 커뮤니티에서 자주 돌아다니는 kimi-k2.5:cloud·glm-5:cloud 목록은 Claude Code가 아니라 Copilot CLI 문서의 권장 목록이다.

페이지를 대조해보지 않으면 그대로 헷갈리기 쉬운 부분이니, 다운로드 전에 어느 도구 문서인지 한 번 더 확인하는 편이 안전하다.

7. 실습 ② Codex App

Codex App은 OpenAI의 macOS·Windows용 데스크톱 코딩 에이전트다.

워크트리와 git 기능을 내장해 여러 Codex 스레드를 병렬로 다룬다.

Ollama가 이 앱에 OpenAI 호환 엔드포인트를 자동으로 구성해 주므로, 로컬 모델과 Ollama Cloud 모델을 데스크톱 앱에서 함께 쓴다.

이번 글에서 가장 손이 많이 가는 실습이라 단계별로 보겠다.

Step 1 — 버전 확인

Codex App 통합은 Ollama v0.24.0에서 처음 추가됐다. 그래서 이 실습은 v0.24.0 이상에서만 동작한다. ollama --version으로 먼저 확인한다.

Step 2 — 한 줄로 설정·실행

ollama launch codex-app

이 명령은 Codex App의 설정을 Ollama 엔드포인트로 바꾸고 앱을 띄운다. 처음 실행하면 설정 파일을 덮어쓰기 전에 백업을 남긴다.

ex) ollama launch codex-app
- 이때도 모델을 선택하게 되어있다. (이번 예시엔 이미 설치되어있는 qwen3:8b 선택)

- codex App이 켜지는데 모델 선택 하는 부분은 보이지 않는다.

- 이에 모델 확인 요청 하니 Qwen임을 확인 가능 하였다.

Step 3 — 백업 위치 확인

Ollama Launch는 Codex App 설정 파일을 덮어쓰기 전에 ~/.ollama/backup/codex-app/에 백업을 저장한다. (Windows에서 ~는 사용자 프로필 디렉터리로 해석된다.) 원래 설정으로 돌아갈 길이 남아 있다는 말이라, 실습이 처음이라도 부담이 덜하다.

Step 4 — 모델 지정해서 실행

기본 선택 대신 원하는 모델을 바로 지정하면 된다. 클라우드 모델과 로컬 모델 예시는 다음과 같다.

# 클라우드 모델 지정
ollama launch codex-app --model kimi-k2.6:cloud

# 로컬 모델 지정
ollama launch codex-app --model gemma4:31b

Codex App 도입 당시 릴리스 노트는 어려운 코딩·에이전트 작업에는 kimi-k2.6·glm-5.1을, 클라우드 구독 없이 로컬로 쓸 때는 nemotron-3-super·gemma4:31b·qwen3.6을 권했다. 현재 문서의 예시도 같은 계열(kimi-k2.6:cloud·gemma4:31b)을 유지한다.

Step 5 — 원래 프로필로 되돌리기

Ollama로 바꾸기 전 프로필로 돌아가려면 --restore를 쓴다.

ollama launch codex-app --restore

이 명령을 실행하면 Ollama가 Codex App의 설정과 구성을 실행 이전 상태로 복원한다. Ollama 모델을 시험만 해보고 원래 쓰던 설정으로 깔끔하게 돌아가고 싶을 때 쓴다.

ex) ollama launch codex-app --restore

- 다시 GPT 5.5 모델로 돌아 오면서 Codex App이 기동되었다.

Codex App이 안 열리거나 모델이 안 바뀔 때

• 설정 후에도 앱이 열리지 않으면, Codex를 수동으로 한 번 연 뒤 ollama launch codex-app을 다시 실행한다.

• 앱이 이미 실행 중인데 모델이 바뀌지 않으면, Ollama가 재시작을 물어볼 때 허용하거나 앱을 완전히 종료한 뒤 다시 실행한다.

Codex App vs Codex CLI

이름이 비슷해 헷갈리기 쉽다.

codex-app은 데스크톱 GUI 앱이고, codex는 터미널 CLI다. CLI는 npm install -g @openai/codex로 설치한 뒤 codex --oss 플래그로 Ollama와 연결한다.

둘은 별개 통합이라 --help 목록에도 따로 올라 있다.

8. 실습 ③ OpenCode

OpenCode는 ollama launch 최초 도입(v0.15.0)부터 함께한 네 통합 중 하나다. 실행은 역시 한 줄이다.

# 바로 실행
ollama launch opencode

# 실행하지 않고 설정만
ollama launch opencode --config

첫 명령은 OpenCode를 설정하고 곧바로 띄운다. --config를 붙이면 실행은 하지 않고 설정만 해 둔다. 지금 당장 열지 않고 나중에 직접 실행하고 싶을 때 쓴다.

OpenCode + Ollama Cloud 모델(glm-4.7:cloud) 구동 화면. 출처:Ollama 공식 블로그 — Launch

공식문서의 캡쳐 화면은 ollama launch opencode --config 이후 OpenCode가 클라우드 모델 glm-4.7:cloud로 응답하는 모습이다.

하단 Build 표시줄에 모델 이름이 보인다.

로컬 모델을 붙였다면 이 자리에 glm-4.7-flash 같은 로컬 모델 이름이 뜬다.

같은 도구를 로컬로도, 클라우드로도 돌린다는 앞의 이야기가 화면에서 그대로 확인된다.

OpenCode도 --model로 바꿀 수 있다

여기서는 기본 흐름만 보였지만, Claude Code·Codex App과 마찬가지로 ollama launch opencode --model <모델명>으로 원하는 모델을 바로 지정하면 된다.

9. --model 플래그 — 매핑은 고정이 아니다

글 서두에서 짚었던 오해를 다시 꺼내보자.

"Claude Code는 이 모델, Codex는 저 모델"처럼 에이전트마다 쓸 모델이 정해져 있다는 생각 말이다.

ollama launch의 기본 프롬프트가 모델을 하나 미리 제시할 뿐이고, --model 플래그만 붙이면 언제든 다른 모델로 바꿀 수 있다.

CLI 문서도 ollama launch claude --model qwen3.5처럼 특정 통합에 원하는 모델을 지정하는 예시를 그대로 보여준다. 다른 에이전트도 마찬가지다.

에이전트	모델 지정 예시
Claude Code	`ollama launch claude --model qwen3.5`
Codex App	`ollama launch codex-app --model kimi-k2.6:cloud`
OpenClaw	`ollama launch openclaw --model kimi-k2.5:cloud`
Pool	`pool -m kimi-k2.6:cloud`

표에서 보듯, 에이전트와 모델의 관계는 고정 배선이 아니라 실행할 때 정하는 옵션이다. 같은 Claude Code를 로컬 qwen3.5로도, 클라우드 glm-4.7:cloud로도 돌린다. "이 도구는 이 모델 전용"이라는 표현을 보면 일단 의심하는 편이 맞다. 페이지에 적힌 권장 모델은 말 그대로 권장일 뿐, 강제 매핑이 아니다.

모델을 바꿔보기 전 체크 두 가지

--model로 다른 모델을 넣어 보기 전에 두 가지만 확인한다. 클라우드 모델(:cloud)이면 ollama signin 로그인 여부, 로컬 모델이면 VRAM이 버티는지다. 이 두 조건만 맞으면 어떤 에이전트에도 원하는 모델을 자유롭게 붙이면 된다.

10. 나머지 에이전트 한눈에 보기

실습으로 다룬 Claude Code·Codex App·OpenCode를 빼면 통합은 13개가 남는다.

각각을 깊게 다루긴 어려우니, 무엇이고 어떻게 실행하는지 표 하나로 묶었다. 대부분 ollama launch <이름> 패턴을 따른다.

표를 보는 법

'실행 / 문서' 열의 명령을 터미널에 그대로 입력하면 대부분 바로 연결된다. 표는 한 줄 설명일 뿐이니, 실제로 써 볼 통합이 있으면 링크를 눌러 옵션까지 문서에서 확인하는 편이 안전하다.

통합	한 줄 설명	실행 / 문서
Hermes Agent	Nous Research의 자가개선형 에이전트. 자동 스킬 생성·세션 간 메모리·기본 70여 개 스킬	`ollama launch hermes` · 문서
Hermes Desktop	Hermes Agent의 데스크톱 채팅 앱 (Nous Research)	`ollama launch hermes-desktop` · 문서
OpenClaw	메시징(WhatsApp·Telegram·Slack 등)을 코딩 에이전트에 연결하는 개인 어시스턴트	`ollama launch openclaw` · 문서
Copilot CLI	GitHub의 터미널용 AI 코딩 에이전트	`ollama launch copilot` · 문서
Codex (CLI)	OpenAI 터미널 CLI. `codex --oss`로 연결	`ollama launch codex` · 문서
Droid	최초 4개 통합 중 하나인 코딩 에이전트	`ollama launch droid` · 문서
OMP (Oh My Pi)	IDE형 터미널 코딩 에이전트 (언어 서버·디버깅·서브에이전트 내장)	`ollama launch omp` · 문서
Pool	Poolside의 엔터프라이즈용 터미널 에이전트	`ollama launch pool` · 문서
Pi	터미널 에이전트 (`--help` 목록 기준)	`ollama launch pi`
Kimi Code CLI	터미널 코딩 CLI (`--help` 목록 기준)	`ollama launch kimi`
Cline	코딩 에이전트 (`--help` 목록 기준)	`ollama launch cline`
Qwen Code	터미널 코딩 CLI (`--help` 목록 기준)	`ollama launch qwen`
VS Code	에디터 통합 (별칭 `code`)	`ollama launch vscode`

표를 만들다 정정할 대목을 하나 발견했다.

Hermes Desktop을 "공식 문서가 없는 통합"으로 적어놨었는데, 실제로 찾아보니 docs.ollama.com/integrations/hermes-desktop에 페이지가 있고 ollama launch hermes-desktop 사용법도 안내하고 있었다.

반대로 Pi·Kimi·Cline·Qwen Code처럼 --help 목록에는 있지만 개별 소개가 얕은 통합도 있으니, 이런 도구는 이름과 실행 명령만 확인하고 실제 문서에서 최신 사용법을 다시 확인하는 편이 안전하다.

11. 계정 로그인이 필요한 기능 (ollama signin)

ollama launch로 도구를 연결하는 것까지는 계정 없이도 되지만, 일부 기능에는 Ollama 계정 로그인이 필요하다.

대표적인 예가 웹서치다. ollama launch openclaw로 실행하면 Ollama 웹서치가 자동으로 켜지는데, 이 웹서치가 Ollama 웹서치 API에 의존하고 그 API는 API 키와 무료 Ollama 계정을 요구하기 때문이다.

클라우드 모델(:cloud)을 쓸 때도 같은 계정 인증이 필요하다.

로그인은 CLI 한 줄이다.

ollama signin

로그인이 필요한 순간

로컬 모델만 쓴다면 로그인 없이도 대부분 동작한다. 하지만 :cloud 모델을 지정하거나 OpenClaw 웹서치 같은 기능을 쓰려는데 인증 오류가 난다면, 먼저 ollama signin을 했는지 확인한다. 로그인을 건너뛴 채 클라우드 기능을 시도하다 막히는 경우가 의외로 흔하다.

로그인 없이도 되는 것

로컬 모델로 ollama launch claude·ollama launch codex-app 같은 기본 연결은 로그인 없이 동작한다. 로그인이 필요해지는 경우는 :cloud 모델을 붙이거나 OpenClaw 웹서치처럼 Ollama 계정 자체가 필요한 기능을 켤 때다.

12. 트러블슈팅 & Q&A

Q. ollama launch를 쳤는데 통합이 몇 개 안 보인다. 지원이 안 되는 건가?

데스크톱 앱 카드는 자주 쓰는 것만 선별해 보여 준다. 전체 지원 목록은 터미널에서 ollama launch --help로 확인한다. 직접 테스트 기준 16개가 나열되며, 카드에 없어도 ollama launch <이름>으로 실행되는 경우가 많다.

Q. 로컬 모델이 자꾸 느리거나 메모리 부족으로 죽는다.

로컬 대형 모델은 VRAM을 많이 요구한다. 예로 glm-4.7-flash는 64000 토큰 컨텍스트에서 약 23GB VRAM이 필요하다. 하드웨어가 못 따라가면 같은 계열의 :cloud 모델로 바꾼다. 모델 이름만 바꾸면 되고, 클라우드는 로컬 사양과 무관하게 전체 컨텍스트 길이를 쓴다.

Q. Codex App을 연결했더니 앱이 안 열린다.

Codex를 수동으로 한 번 연 뒤 ollama launch codex-app을 다시 실행한다. 이미 실행 중인데 모델이 안 바뀌면 Ollama가 재시작을 물어볼 때 허용하거나 앱을 종료한 뒤 다시 실행한다. 원 설정으로 돌리고 싶으면 --restore를 쓴다.

Q. 컨텍스트 길이는 얼마로 잡아야 하나?

공식 블로그는 코딩 도구용으로 최소 64000 토큰을 권한다. Claude Code는 최소 32K를, Copilot CLI는 최소 64k를 권장하는 식으로 도구마다 하한이 다르다. 값이 클수록 큰 리포지토리를 다루기 유리하므로, 64000 토큰을 기준으로 잡고 필요하면 올린다.

Q. 클라우드 모델 요금이 궁금하다.

공식 블로그는 이번 업데이트로 사용량이 늘고 5시간짜리 확장 코딩 세션 윈도우를 제공한다고 밝혔다. 다만 구체적인 요금과 한도는 시점에 따라 바뀔 수 있으므로, 결정 전에 Ollama 요금 페이지에서 최신 정보를 확인한다.

13. 마무리 — 로컬과 클라우드, 무엇을 고를까

여기까지 직접 돌려보고 정리하고 나니, ollama launch의 진짜 이점은 "에이전트를 바꾸든 모델을 바꾸든 명령 한 줄"이라는 데 있다는 걸 보여주고 싶었다.

그러면 남는 질문은 도구 선택이 아니라 로컬과 클라우드 중 무엇을 언제 쓰느냐다.

상황	추천	이유
코드가 외부로 나가면 안 됨	로컬	연산이 내 컴퓨터를 벗어나지 않는다
오프라인·네트워크 불안정	로컬	네트워크 없이 동작한다
VRAM이 부족(노트북 등)	클라우드(`:cloud`)	로컬 사양과 무관하게 전체 컨텍스트를 쓴다
큰 리포지토리·긴 컨텍스트	클라우드(`:cloud`)	전체 컨텍스트 길이 지원
일단 연결부터 확인	클라우드(`:cloud`)	대형 모델 다운로드 시간을 건너뛴다

공식 가이드가 정리해 주지 않는 것 — "권장 모델"의 파편화

이 글을 쓰면서 느낀 건데, Ollama 공식 페이지들은 "이 에이전트엔 이 모델"을 한곳에 모아 주지 않는다. 실제로 2026-07-02 기준 Claude Code 문서에는 권장 모델 섹션 자체가 없고, 같은 kimi-k2.5:cloud·glm-5:cloud 목록이 Copilot CLI 문서에 있다. 어시스턴트 계열(OpenClaw·Hermes)은 또 다른 4종을 권한다. "정답 모델"을 찾겠다고 페이지를 옮겨 다니면 오히려 헷갈리기만 한다. 차라리 --model로 몇 개 직접 돌려 보고 내 리포지토리에서 잘 맞는 것을 고르는 편이 현실적이다.

독자 적용 체크리스트

ollama --version으로 v0.15+인지 확인하고, 아니면 업데이트한다.
ollama launch --help를 실행해 내 환경이 지원하는 통합 목록을 직접 확인한다.
Ollama 설정에서 컨텍스트 길이를 64000 토큰 이상으로 올린다.
클라우드 모델을 쓸 계획이면 ollama signin으로 먼저 로그인한다.
같은 에이전트를 --model로 로컬·클라우드 모델을 번갈아 실행해 응답 차이를 비교한다.

단계별 도입 플레이북

오늘: Ollama를 v0.15+로 올리고 ollama launch claude 또는 ollama launch codex-app으로 한 도구를 연결한다.
이번 주: :cloud 모델과 로컬 모델을 각각 붙여 응답 속도·품질을 비교하고, 자주 쓰는 조합을 정한다.
자동화한다면: --yes와 --model을 조합해 스크립트·CI에 코드 리뷰나 요약 작업을 걸어 둔다.

거창하게 준비할 것 없다. 지금 터미널을 열어 ollama launch --help부터 실행해 보면, 내 환경이 어떤 에이전트를 지원하는지 30초 안에 확인된다.

참고 자료

같이 보면 좋은 글

공식 블로그·문서

GitHub 릴리스 (버전·기능 시점 교차검증)

작성일: 2026년 7월 2일 | 기준 버전: Ollama 0.30.11 (직접 테스트) | 통합 개수: ollama launch --help 기준 16개

통합 개수·권장 모델·요금·컨텍스트 권장치는 업데이트에 따라 달라질 수 있다. 적용 전 공식 문서를 최우선으로 확인하는 편이 안전하다. 요금·한도 정보는 시점에 따라 바뀔 수 있으므로 Ollama 요금 페이지에서 최신 정보를 확인한다.

저작자표시 비영리 변경금지 (새창열림)

'AI > Open Models' 카테고리의 다른 글

ZCode란? GLM-5.2 + ZCode 사용방법 - GLM 제작사가 만든 Claude Code 대항마(z.ai 가입, GLM Coding Plan, API 키 발급 등) (2)	2026.07.02

Contents

당신이 좋아할만한 콘텐츠

ZCode란? GLM-5.2 + ZCode 사용방법 - GLM 제작사가 만든 Claude Code 대항마(z.ai 가입, GLM Coding Plan, API 키 발급 등) 2026.07.02

새소식