로컬 AI에서 코딩 에이전트 실행하기 — 클라우드 없이 완전한 제어권 확보

코딩 에이전트(Coding agents) — Codex CLI, Claude Code, Cursor, Pi — 는 생산성을 배가시켜 줍니다. 하지만 이들은 모두 당신의 코드를 타인의 서버로 보내는 것에 동의한다고 가정합니다. 독점적인 코드베이스(proprietary codebases), 고객 NDA(비밀유지계약), 컴플라이언스(compliance) 요구사항, 또는 단순히 자신의 컴퓨팅 자원을 소유하겠다는 원칙 때문에 많은 이들에게 이는 수용할 수 없는 문제입니다.

이 가이드는 모든 클라우드 API를 qwen3-coder:30b를 실행하는 로컬 Ollama 서버로 교체하는 방법을 보여줍니다. 동일한 도구, 동일한 워크플로우를 사용하면서도 데이터는 네트워크를 벗어나지 않습니다.

왜 AI를 로컬에서 실행해야 하는가?

이유는 간단합니다:

• 데이터 유출 제로 (Zero data exfiltration). 당신의 코드는 기기나 LAN을 절대 벗어나지 않습니다.
• 토큰당 비용 없음. 10,000번의 완성(completions)을 수행하든 10번을 수행하든, 전기 요금은 상관하지 않습니다.
• 오프라인 작동. 비행기 모드, 제한된 네트워크, 불안정한 VPN — 모두 상관없습니다.
• 속도 제한(Rate limits) 없음. 몰입 중인 새벽 2시에 429 에러(Too Many Requests)를 만날 일이 없습니다.

솔직한 트레이드오프(tradeoff)를 말하자면: 프런티어 모델(frontier models, Claude Opus 4, GPT-5)은 복잡한 다단계 추론(multi-step reasoning) 및 매우 큰 컨텍스트(context) 작업에서 여전히 로컬 모델보다 성능이 뛰어납니다. 하지만 자동 완성(autocomplete), 리팩터링(refactors), 테스트 생성(test generation), 문서화(documentation)와 같은 일상적인 코딩 작업의 80%에 대해서는 잘 선택된 로컬 모델만으로도 충분하고도 남습니다.

하드웨어 요구사항

저는 이를 48GB 통합 메모리(unified memory)를 갖춘 Apple M4 Pro에서 실행합니다. Apple Silicon의 통합 메모리 아키텍처는 LLM 추론(inference)에 매우 적합합니다. GPU와 CPU가 동일한 메모리 풀을 공유하므로, 22GB 모델이 전체 개발 환경과 함께 여유롭게 들어갈 수 있습니다.

최소 실행 가능 설정:

RAM	수용 가능한 모델
16 GB	7–8B 파라미터 모델 (qwen3:8b, llama3.2:8b)
...

외장 GPU가 있는 Intel/AMD 시스템의 경우 계산 방식이 다릅니다. VRAM이 병목 현상(bottleneck)이 되며, VRAM에 완전히 들어가지 않는 모델은 느린 CPU 오프로딩(offloading)으로 전환됩니다.

모델 선택

48GB 통합 메모리의 경우, 알아둘 가치가 있는 모델들은 다음과 같습니다:

모델	디스크 용량	활성 파라미터 (Active params)	강점
qwen3-coder:30b	~22 GB	3.3B (MoE)	코딩, 256K 컨텍스트 (context), HumanEval SOTA
...

qwen3-coder:30b는 코딩 작업을 위한 기본 권장 모델입니다. 이 모델은 전문가 혼합 (Mixture-of-Experts, MoE) 아키텍처를 사용하여 토큰당 3.3B의 파라미터만 활성화되므로, 전체 파라미터 수에도 불구하고 추론 (inference) 속도가 빠릅니다. 256K 컨텍스트 창 (context window)은 코드베이스 전체를 청킹 (chunking) 없이 처리할 수 있습니다. 또한 HumanEval 벤치마크에서 GPT-4o를 능가합니다.

Ollama로 가져오기:

ollama pull qwen3-coder:30b

Ollama를 네트워크 서버로 설정하기

기본적으로 Ollama는 localhost에서만 대기합니다. LAN(근거리 통신망) 내의 다른 기기에서 접속하거나 (또는 자체적인 네트워크 연결을 여는 코딩 도구들이 접속할 수 있도록 하려면), 모든 인터페이스에 바인딩(bind)해야 합니다:

OLLAMA_HOST=0.0.0.0 ollama serve

macOS에서 이를 영구적으로 적용하려면, Ollama 실행 에이전트(launch agent)를 편집하거나 Ollama를 시작하기 전에 셸 프로필(shell profile)에 환경 변수를 설정하십시오. 그러면 서버는 다음 주소로 접속 가능해집니다:

192.168.2.200을 귀하의 기기 LAN IP로 바꾸십시오. 작동 여부를 확인하려면 다음을 실행하십시오:

curl http://192.168.2.200:11434/api/tags | jq '.models[].name'

Ollama는 OpenAI와 호환되는 /v1 엔드포인트 (endpoint)를 노출하며, 아래의 모든 도구들이 이를 사용합니다.

Codex CLI

Codex CLI는 OpenAI의 터미널 기반 코딩 에이전트입니다. TOML 설정을 통해 사용자 정의 모델 제공자 (model providers)를 지원합니다.

설치

npm install -g @openai/codex

설정

~/.codex/config.toml 파일을 생성하십시오:

model = "qwen3-coder:30b"
model_provider = "ollama_remote"
model_context_window = 262144
...

직접 겪으며 발견한 몇 가지 주의 사항(gotchas)은 다음과 같습니다:

직접 겪으며 발견한 몇 가지 주의 사항(gotchas)은 다음과 같습니다:

• Provider ID는 하이픈(-)이 아닌 언더스코어(_)를 사용해야 합니다. ollama-remote는 파싱 에러(parse error)가 발생하며, ollama_remote는 정상 작동합니다.
• [model_providers.*] 설정 시 name은 필수 항목입니다. 이를 누락하면 provider name must not be empty 에러가 발생합니다.
• ollama, openai, lmstudio는 예약된(reserved) 내장 프로바이더 ID이므로 재정의할 수 없습니다. 항상 ollama_remote와 같은 사용자 정의 이름을 사용하십시오.
• model_context_window는 명시적으로 설정해야 합니다. Codex는 알 수 없는 모델에 대해 이 값을 자동으로 추론하지 않습니다.

API 키 환경 변수를 설정하십시오 (Ollama는 인증이 필요하지 않지만, Codex는 이 변수 없이는 시작되지 않습니다):

export OLLAMA_API_KEY=ollama

모델 카탈로그 (Model Catalog)

모델 카탈로그가 없으면 Codex는 Model metadata for qwen3-coder:30b not found를 출력하고 작동하지 않는 기본값으로 되돌아갑니다. 카탈로그 형식은 Codex의 번들 스키마(bundled schema)에 포함된 모든 필드를 요구합니다. 몇 개의 키만 포함된 단순화된 JSON은 missing field 에러와 함께 실패합니다.

가장 깔끔한 방법은 Codex 자체의 번들 메타데이터로부터 카탈로그를 생성하고 여기에 사용자의 모델을 패치(patch)하는 것입니다:

codex debug models --bundled | python3 -c "
import json, sys
d = json.load(sys.stdin)
...

두 가지 핵심 필드는 supported_reasoning_levels: []와 supports_reasoning_summaries: false입니다. 이 필드들이 없으면 Codex는 thinking 파라미터를 전송하며, Ollama는 이를 does not support thinking이라며 거부합니다. qwen3-coder:30b는 체인 오브 서트 (Chain-of-thought, CoT) 추론을 지원한다는 점에 유의하십시오. Qwen3 모델은 <think> 태그를 통해 내부적으로 추론합니다. 이 API 파라미터를 비활성화하는 것은 단지 Codex가 Ollama가 수용할 수 없는 OpenAI 전용 형식으로 해당 파라미터를 요청하는 것을 방지할 뿐입니다.

카탈로그가 올바르게 로드되었는지 확인하십시오:

OLLAMA_API_KEY=ollama codex debug models | python3 -c "
import json, sys
d = json.load(sys.stdin)
...

Codex 실행하기

OLLAMA_API_KEY=ollama codex

또는 ~/.zshrc에 영구적으로 추가하십시오:

export OLLAMA_API_KEY=ollama

그 후 어떤 프로젝트 디렉토리에서든 codex를 실행하면 됩니다.

Claude Code

Claude Code는 Anthropic의 공식 CLI 에이전트입니다. 이 에이전트는 Anthropic API에 고정되어 있지만, 베이스 URL (base URL) 재정의를 허용합니다. 즉, Ollama를 포함하여 OpenAI와 호환되는 모든 엔드포인트(endpoint)를 지정할 수 있음을 의미합니다.

설정 (Configuration)

Claude Code를 실행하기 전에 두 개의 환경 변수(environment variables)를 설정하세요:

export ANTHROPIC_BASE_URL=http://192.168.2.200:11434
export ANTHROPIC_API_KEY=ollama

Claude Code를 시작합니다:

claude

로그인 프롬프트가 나타나면, 로그인 방법으로 **"Anthropic Console"**을 선택하세요. Claude Code는 api.anthropic.com 대신 사용자가 제공한 베이스 URL을 사용하게 됩니다.

이 설정을 영구적으로 적용하려면, 셸 프로필(~/.zshrc, ~/.bashrc)에 export 명령어를 추가하세요:

# Claude Code를 위한 로컬 AI 백엔드 (Local AI backend)
export ANTHROPIC_BASE_URL=http://192.168.2.200:11434
export ANTHROPIC_API_KEY=ollama

그 다음 다시 로드합니다:

source ~/.zshrc

실용적인 참고 사항 하나: Claude Code의 시스템 프롬프트(system prompts)는 Claude 모델에 맞춰 작성되었으며 Anthropic 특유의 포맷팅(formatting) 기대치가 포함되어 있습니다. qwen3-coder:30b는 이를 잘 처리하지만, 응답에서 간혹 포맷팅이 어색한 경우가 발생할 수 있습니다. 이는 기능에는 영향을 미치지 않습니다.

Cursor

Cursor도 유사한 설정 경로를 가집니다. Settings → Models → OpenAI API Key에서 커스텀 베이스 URL로 전환하세요:

1. Cursor Settings (Cmd+,)를 엽니다.
2. Models로 이동합니다.
3. **"Override OpenAI Base URL"**을 활성화합니다.
4. http://192.168.2.200:11434/v1을 입력합니다.
5. API 키로 ollama를 입력합니다.
6. 모델로 qwen3-coder:30b를 선택하거나 입력합니다.

Pi (pi.dev)

Pi는 확장성을 위해 구축된 최소한의 에이전트 하네스(agent harness)입니다. "Pi를 당신의 워크플로우에 맞추세요, 그 반대가 아니라."라는 철학을 가지고 있습니다. Pi는 15개 이상의 프로바이더(providers)를 지원하며, 세션 사이에 핫 리로드(hot-reloads)되는 models.json 파일을 통해 커스텀 로컬 엔드포인트를 지원합니다.

설치 (Install)

npm install -g @pi-ag/coding-agent

설정 (Configuration)

~/.pi/agent/models.json에 로컬 Ollama 서버를 추가하세요:

{
  "providers": {
    "ollama_remote": {
...

compat 블록이 중요합니다: Ollama는 Pi가 추론 가능 모델(reasoning-capable models)에 기본적으로 보내는 developer 역할(role)이나 reasoning_effort 파라미터를 이해하지 못합니다. 두 항목을 모두 false로 설정하면 이러한 오류를 우회할 수 있습니다.

Pi 실행하기

pi

세션 내부에서 /model 명령어를 사용하여 모델을 선택하세요. 여기에는 사용자가 정의한 ollama_remote 항목을 포함한 모든 프로바이더(providers)가 나열됩니다. models.json 파일은 /model을 열 때마다 다시 로드되므로, 재시작 없이도 모델을 추가하거나 교체할 수 있습니다.

도입 전 고려해야 할 트레이드오프 (Tradeoffs)

이 도구를 완벽한 대체재라고 홍보하기보다는 한계점에 대해 솔직하게 인지하는 것이 더 중요합니다.

qwen3-coder:30b가 클라우드 모델과 대등하거나 능가하는 부분:

• 단일 파일 리팩토링 (refactors) 및 재작성 (rewrites)
• 기존 코드로부터 테스트 생성
• 문서화 및 주석 생성
• 코드 리뷰 및 코드 동작 설명
• SQL 쿼리, 쉘 스크립트 (shell scripts), 설정 파일 (configuration files)
• 반복적인 보일러플레이트 (boilerplate) 코드

프런티어 모델 (frontier models)이 여전히 우위에 있는 부분:

• 심도 있는 파일 간 추론 (cross-file reasoning)이 필요한 다중 파일 아키텍처 변경
• 모델이 매우 큰 컨텍스트 (context)를 동시에 유지해야 하는 작업 (단, 256K 컨텍스트가 큰 도움이 됩니다)
• 복잡한 도메인에서의 새로운 알고리즘 설계
• 생소한 코드 패턴에서 미묘한 보안 취약점 포착

운영 측면의 고려 사항:

• 모델을 로드한 후 첫 번째 추론 (inference)에는 몇 초가 소요됩니다. 이후의 호출은 빠릅니다.
• Mac이 절전 모드로 들어가면 Ollama도 일시 중단됩니다. 작업 중에는 "컴퓨터가 잠자기 상태로 전환되지 않도록 방지" 설정을 켜두는 것이 좋습니다.
• Ollama 서버는 기본적으로 인증 절차가 없습니다. 반드시 LAN 내에서만 사용하세요. 포트 11434를 인터넷에 노출해서는 안 됩니다.

기타 작업을 위한 모델 선택에 관한 참고 사항

만약 qwen3-coder:30b가 특정 작업에 적합하지 않다면, 다음과 같은 경우에 전환하십시오:

• 비전 작업 (Vision tasks) (스크린샷, 문맥 내 다이어그램): qwen3.6:35b를 사용하십시오 — 멀티모달 (multimodal) 지원 기능이 있습니다.
• 에이전트 워크플로우 (agentic workflows)에서의 헤비한 함수/도구 호출 (Heavy function/tool calling): gpt-oss:20b가 더 신뢰할 수 있는 구조화된 출력 (structured output)을 제공합니다.
• 수학 또는 형식적 추론 (Math or formal reasoning): gemma4:27b는 추론 벤치마크에서 강력한 성능을 보입니다.
• 추론 과정 (reasoning trace)을 확인하고 싶은 사고의 사슬 (Chain-of-thought) 문제: deepseek-r1:70b를 사용하십시오 (45GB 이상의 여유 RAM이 필요합니다).

Ollama에서 모델을 전환하는 것은 즉각적입니다 — 모델을 pull한 뒤 설정 파일의 model 필드만 업데이트하면 됩니다.

결론

클라우드 API를 로컬 Ollama 서버로 교체하는 것은 비용 없음, 데이터 노출 없음, 속도 제한(rate limits) 없음이라는 영구적인 이점을 제공하는, 단 하루(one-afternoon)면 끝나는 프로젝트입니다. 설정에는 세 개의 설정 파일과 두 개의 환경 변수(environment variables)가 필요합니다.

qwen3-coder:30b는 대부분의 코딩 작업에서 클라우드의 필요성을 느끼지 못할 정도로 충분한 능력을 갖추고 있습니다. 최첨단(frontier-level) 추론이 필요한 시점에도 클라우드는 여전히 존재하지만, 이제는 기본값이 아닌 선택 사항(opt-in)이 됩니다.

핵심 통찰은 여러분의 하드웨어, 코드, 그리고 워크플로우가 여러분의 통제 하에 있어야 한다는 것입니다. 도구들은 언제나 호환 가능한 엔드포인트(endpoint)에 연결될 준비가 되어 있었습니다. 이제 여러분은 그 도구들에게 여러분이 소유한 엔드포인트를 제공하는 방법을 알게 되었습니다.