Claude Code는 사용자 컴퓨터의 Ollama가 제공하는 모델을 통해 사용자가 소유한 저장소에서 작업할 수 있습니다. Ollama의 현재 Claude Code 통합은 Anthropic 호환 API를 통해 직접 연결됩니다. 이 가이드는 범위를 제한한 코드 변경 한 건을 기록된 초기 상태부터 사람이 diff를 판단하는 단계까지 다룹니다. 두 도구를 설치하고 저장소 편집을 승인하며 적절한 로컬 코딩 모델을 실행할 수 있는 개발자를 대상으로 합니다. BIG CHANGE는 2026년 10월 20일 매뉴얼을 확인했으며, 모델을 실행하거나 저장소를 테스트하지는 않았습니다.

핵심 변화

  • 달라진 점: Ollama는 이제 실행 도구 또는 명시적인 로컬 엔드포인트 설정을 사용하여 Claude Code를 로컬 Anthropic 호환 서버에 직접 연결하는 경로를 문서화합니다. 문서에 제시된 이 구성에는 별도 프록시가 필요하지 않습니다.
  • 중요한 이유: Claude Code 작업 흐름을 유지하면서 로컬 모델을 선택하고, 실제 컨텍스트 할당량을 확인하고, 실제 저장소 편집을 프로젝트의 원래 인수 검사와 대조해 검토할 수 있습니다.
  • 주의할 점: 로컬 태그를 선택하고 모델이 실행 중이라는 사실만으로 모든 요청이 로컬에 머물렀거나 코드가 올바르다고 입증되지는 않습니다. 변경을 수락하기 전에 실제 라우팅, 도구 접근 권한, 전체 diff와 검사 결과를 확인하세요.

1. 저장소의 초기 상태 기록하기

직접 소유하거나 변경 권한이 있는 Git 저장소에서 작업하세요. 검토 가능한 브랜치나 폐기 가능한 체크아웃을 사용하세요. 변경할 작은 동작이나 결함 한 가지, 영향을 줄 수 있는 파일과 중단 조건을 정하세요. 문서에 있는 테스트 또는 빌드 검사처럼 저장소에 이미 마련된 인수 명령을 찾고, 일반적인 명령으로 대체하지 마세요. 에이전트가 편집하기 전에 실행하여 명령, 종료 상태와 관련 출력을 기록하세요. 브랜치, git status 및 기존 diff도 기록하세요. 기존 변경은 초기 상태에 포함되며 AI의 결과가 아닙니다.

조직의 코드 및 의존성 정책이 선택한 모델과 도구를 허용하는지 확인하세요. Claude Code는 적용되는 권한 설정에 따라 파일을 읽고 명령을 실행할 수 있습니다. “이 파일만 수정하라”는 요청은 에이전트를 안내할 뿐 파일 시스템 접근을 제한하지 않습니다.

2. 적절한 로컬 모델 설치 및 컨텍스트 할당하기

최신 Ollama 릴리스와 Claude Code CLI를 컴퓨터 및 조직의 규칙에 따라 공식 지침으로 설치하세요. ollama --version 및 claude --version의 결과를 기록하세요. Ollama는 2026년 1월 버전 0.14.0에서 Anthropic Messages 호환성을 도입했지만, 이 날짜가 현재 실행 명령의 최소 버전을 의미하지는 않습니다. 현재 ollama launch 명령의 요구 사항은 따로 확인하세요.

현재 카탈로그 항목에 도구 지원이 명시되어 있고 사용 목적이 라이선스상 허용되며 가중치 및 컨텍스트 할당량이 컴퓨터 용량에 맞는 모델을 선택하세요. 구체적인 로컬 예시는 qwen3-coder:30b입니다. 도구 지원, 약 19 GB의 Q4_K_M 파일 및 Apache License 2.0이 명시되어 있습니다. 이 크기는 다운로드 용량이며 RAM이나 VRAM 요구량이 아닙니다. 모델에 표시된 컨텍스트 길이를 컴퓨터에서 실제로 할당할 수 있다는 뜻도 아닙니다. 이 모델이 맞지 않으면 도구 지원이 문서화된 다른 로컬 태그를 고르고 이후 명령의 태그를 모두 일관되게 바꾸세요.

Ollama 앱 또는 로컬 서버가 실행된 뒤 터미널에서 모델을 내려받고 정확한 태그를 확인하세요:

Text
ollama pull qwen3-coder:30b
ollama list

Ollama는 코딩 에이전트에 최소 64,000토큰을 권장합니다. 또한 컨텍스트가 클수록 메모리를 더 사용한다고 설명합니다. 하드웨어가 지원한다면 기존 Ollama 앱의 설정에서 64k 이상을 지정하세요. 서버를 직접 운영한다면 기존 서비스에 OLLAMA_CONTEXT_LENGTH=64000를 설정하되 플랫폼별 서버 지침을 따르세요. 포트 11434에서 두 번째 서버를 시작하지 마세요. 모델 요청이 로드된 후 ollama ps에서 실제 CONTEXT 및 PROCESSOR 값을 확인할 수 있습니다. 원하는 할당량으로 로드할 수 없다면 중단하거나 작업 범위를 줄이고 적절한 구성을 선택하세요. 카탈로그의 최댓값을 실제 할당된 컨텍스트로 보고하지 마세요.

3. Claude Code를 로컬 서버로 연결하기

터미널을 선택한 저장소에서 여세요. Ollama는 이 실행 도구 경로를 문서화합니다. ollama list에서 확인한 것과 동일한 로컬 태그를 사용하세요:

Text
ollama launch claude --model qwen3-coder:30b

Ollama는 Claude가 아닌 모델을 사용하는 이 경로를 문서화합니다. Anthropic의 게이트웨이 매뉴얼은 게이트웨이를 통해 Claude Code를 Claude가 아닌 모델에 연결하는 방식을 Anthropic이 지원하지 않는다고 명시합니다. 이 연결 방식에 대한 Anthropic의 지원 없이 Ollama가 문서화한 통합으로 이해하고, 의존하기 전에 실제 세션을 확인하세요.

수동 구성의 경우 Ollama의 통합 지침에서는 대신 ANTHROPIC_AUTH_TOKEN=ollama, 명시적으로 비워 둔 ANTHROPIC_API_KEY 및 ANTHROPIC_BASE_URL=http://localhost:11434을 사용합니다. 이 선택 사항인 Bash 명령은 소유한 저장소 디렉터리에서 해당 Claude Code 프로세스에만 세 값을 설정하며 전역 셸 프로필을 바꾸지 않습니다:

Terminal
ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_API_KEY="" ANTHROPIC_BASE_URL=http://localhost:11434 claude --model qwen3-coder:30b

다른 셸에서는 위의 권장 Ollama 실행 도구나 최신 공식 매뉴얼의 셸별 설정을 사용하세요. 명령의 변수보다 우선할 수 있는 기존 Claude Code 설정을 확인하세요. 설정 확인 중 기존 자격 증명을 출력하지 마세요. 실제 설정을 다시 읽었을 때 예상되는 값은 선택한 로컬 태그와 http://localhost:11434입니다. 이는 독자가 수행할 검사이며 BIG CHANGE가 관찰한 결과가 아닙니다. 로컬 서버는 ollama 자리표시자 토큰을 무시하므로 이 값은 접근 제어용 비밀이 아닙니다. 문서화된 로컬 경로에는 Ollama 클라우드 키나 Anthropic 추론 키가 필요하지 않습니다. Claude Code 소프트웨어 약관과 연결된 서비스의 조건은 여전히 적용됩니다.

Ollama의 서버 구성 지침에 따라 서버가 로컬에 바인딩된 상태를 유지하세요. :cloud 태그나 https://ollama.com 기본 URL은 데이터와 비용을 별도로 판단해야 하는 클라우드 경로입니다. 모델이나 목적지가 불분명하면 저장소 내용을 보내기 전에 중단하세요.

4. 경로를 확인하고 편집 한 건 요청하기

파일 변경을 허용하기 전에 /status를 사용할 수 있다면 Claude Code의 실제 모델과 연결을 확인하세요. 확인한 값을 실행 도구 또는 수동 엔드포인트, ollama list, 그리고 요청으로 모델이 로드된 후의 ollama ps와 비교하세요. 실제로 로드된 정확한 태그, 할당된 CONTEXT 및 PROCESSOR를 기록하세요. CPU로 분산 처리되는 정도에 따라 작업 흐름의 실용성이 달라질 수 있습니다. 가능하면 로컬 서버의 요청 증거도 확인하세요. 이 검사는 구성과 모델 로드를 확인할 뿐 모든 네트워크 트래픽을 완전히 감사하지는 않습니다. 로컬 처리가 코드 정책상 중요하다면 활성 MCP 도구, 웹 가져오기 및 검색, 원격 측정과 클라우드 설정을 별도로 검토하세요.

Claude Code의 일반적인 승인 요청과 권한 제어를 사용하세요. 소유한 저장소의 작업 한 가지를 일상 언어로 요청하면서 필요한 동작, 허용 범위, 원래의 인수 명령과 중단 지점을 명시하세요. 변경 파일과 검사 출력을 보고하도록 요청하세요. 커밋, 푸시 및 릴리스 결정은 저장소 소유자가 내리고, 예상치 못한 네트워크나 도구 동작은 거절하세요. 모델이 로컬 엔드포인트를 사용했거나 검사를 통과했다고 주장하는 것만으로 검증되지는 않습니다.

5. 전체 diff와 원래 검사에 근거해 판단하기

변경된 모든 파일과 전체 Git diff를 살펴보고 요청 범위를 벗어난 변경도 확인하세요. 새 의존성의 라이선스를 포함하여 원래 동작 및 저장소 정책과 변경을 대조하세요. 편집 후에는 기록해 둔 동일한 인수 명령을 직접 실행하세요. 종료 상태와 관련 출력을 초기 상태와 함께 기록하세요. diff가 요청과 일치하고, 독립적인 검사 결과가 허용 가능하며, 라우팅과 권한 증거가 요구 사항을 충족할 때만 변경을 수락하세요. 그렇지 않으면 브랜치를 수락하지 않은 상태로 두고 검토를 위해 정확한 실패 내용을 보존하세요.

Ollama에 연결할 수 없다면 코딩 작업을 시도하기 전에 실행 중인 앱이나 서비스와 ollama list를 확인하세요. 모델을 로드할 수 없거나 ollama ps에서 컨텍스트 부족이 나타나면 메모리와 컨텍스트 설정을 확인하고, 범위가 더 작은 작업이나 적절한 로컬 모델을 사용하세요. /status 또는 실제 설정에 호스팅 제공자가 나타나면 코드를 보내기 전에 중단하고 현재 셸이나 Claude Code 설정을 수정하세요. 도구 호출 오류는 모델 호환성이나 권한 거부 때문일 수 있으므로 둘 중 어느 것을 바꾸기 전에 정확한 응답을 확인하세요. 이미 파일이 편집되었다면 되돌리거나 계속하기 전에 diff를 살펴보세요. 인수 검사가 실패하면 코드를 진단하고 검토된 수정 후에만 다시 검사하세요.

로컬 추론은 내려받은 모델에 대한 제공자의 토큰당 추론 요금을 피하지만 하드웨어, 저장 공간과 전기를 사용합니다. 다운로드, 원격 측정, 웹 도구, MCP 통합이나 클라우드 모델 설정은 데이터를 보내거나 다른 비용을 발생시킬 수 있습니다. Ollama는 Anthropic Messages API의 일부를 지원하며 토큰 계산, 프롬프트 캐싱, 배치, 인용, PDF와 강제 도구 선택 등의 기능에는 제한이 있습니다. 모델마다 도구 사용 능력도 다릅니다. BIG CHANGE의 문서 검토로 측정된 속도, 품질, 개인정보 보호 또는 절감 결과는 없습니다. 다른 로컬 에이전트 구성은 Junie Local 가이드를 참고하세요. 이 절차는 Claude Code를 유지하면서 Ollama 경로를 확인하는 데 초점을 둡니다.

출처 및 추가 자료

  • Ollama, “Claude Code”는 현재 실행 도구, 수동 로컬 설정과 클라우드 대안을 제공합니다. 경로를 문서화할 뿐 독자의 저장소에서 성공적으로 실행되었음을 뜻하지 않습니다.
  • Ollama, “Anthropic compatibility”는 로컬 엔드포인트, 무시되는 자리표시자 토큰, 모델 내려받기 및 API 기능 제한을 설명합니다. 호환성이 모든 모델이나 도구 호출을 보증하지는 않습니다.
  • Ollama, “Context length”는 코딩용 64k 권장 사항, 메모리 사용의 대가와 ollama ps의 결과 확인을 설명합니다. 실제 컴퓨터가 가능한 할당량을 결정합니다.
  • Ollama의 qwen3-coder:30b 항목에는 예시 파일, 도구와 Apache 2.0 라이선스 링크가 있습니다. 내려받거나 재배포하기 전에 정확한 모델 항목을 다시 확인하세요.
  • Claude Code 설치 및 권한 설정은 접근과 도구 승인을 설명합니다. 어느 것도 특정 세션의 실제 엔드포인트나 안전한 저장소 결과를 입증하지 않습니다.
  • Anthropic, “Other LLM gateways”는 게이트웨이로 Claude Code를 Claude가 아닌 모델에 연결하는 방식을 Anthropic이 지원하지 않는다고 명시합니다. Ollama는 여기서 설명한 로컬 통합을 별도로 문서화합니다.