코딩 에이전트와 로컬 모델 연결하기 (클로드 코드, 코덱스, 올라마)

🤔 구독 한도 없이 로컬 모델로 에이전트를 돌리고 싶을 때

클로드 코드나 코덱스 CLI를 쓰다 보면 사용량 한도가 신경 쓰이고, 회사 코드를 밖으로 보내기 부담스러운 때도 있습니다. 그래서 집 컴퓨터에 올려 둔 로컬 모델로 같은 에이전트를 돌릴 수 있는지 궁금해집니다. 결론부터 말하면 연결은 됩니다. 다만 "주소만 바꾸면 똑같이 쓴다"는 설명은 절반만 맞습니다.

지금부터 클로드 코드와 코덱스 CLI를 올라마 로컬 모델에 붙이는 방법, 연결이 제대로 동작하려면 필요한 조건, 공식 문서가 직접 밝힌 한계를 정리합니다. 올라마 서버 자체의 설정은 로컬 모델 서빙 기초에서 다뤘습니다. 명령과 설정은 2026년 9월 28일 공식 문서 기준입니다.

🔑 코딩 에이전트와 로컬 모델 연결의 정의

코딩 에이전트를 로컬 모델에 연결한다는 것은 에이전트가 요청을 보내는 주소를 내 컴퓨터의 모델 서버로 바꿔, 파일 읽기와 명령 실행 같은 에이전트 동작을 로컬 모델의 판단으로 돌리는 일입니다.

코딩 에이전트는 파일을 읽고 명령을 실행하는 도구 부분과, 다음에 무엇을 할지 정하는 모델 부분으로 나뉩니다. 로컬 연결은 이 가운데 모델 부분만 바꾸는 것입니다. 파일을 고치고 명령을 실행하는 동작은 그대로지만, 어떤 파일을 열고 어떤 명령을 쓸지 판단하는 두뇌가 내 컴퓨터의 모델로 바뀝니다. 그래서 결과의 품질은 거의 전부 그 모델의 실력에 달려 있습니다.

🔗 도구별 연결 방법

도구마다 요청 형식이 달라서 붙는 경로도 다릅니다.

ollama launch는 올라마가 공식으로 지원하는 연결 명령입니다. 모델을 고르는 화면을 띄우고 설정까지 해 준 뒤 에이전트를 실행하며, ollama launch claude --model qwen3.5처럼 모델을 바로 지정할 수도 있습니다.

클로드 코드를 직접 설정할 때는 올라마 문서의 환경 변수를 그대로 씁니다.

여기서 짚을 점은 주소가 /v1로 끝나는 OpenAI 호환 경로가 아니라는 것입니다. 클로드 코드는 Anthropic 메시지 형식(/v1/messages)으로 요청하므로, OpenAI 호환 주소만 제공하는 서버에는 붙지 않습니다. 클로드 설정 파일이 셸 변수를 덮어쓸 수 있으므로 연결한 뒤 /status로 실제 주소를 확인합니다. 클로드 코드는 백그라운드 기능에 haiku 별칭의 모델을 쓰는데, 이 별칭이 가리킬 모델은 ANTHROPIC_DEFAULT_HAIKU_MODEL로 따로 지정할 수 있습니다. LM Studio도 공식 문서에 같은 방식의 예를 두고 있으며, 주소는 http://localhost:1234, 인증 값은 lmstudio입니다.

코덱스 CLI는 --oss 옵션으로 올라마나 LM Studio 같은 로컬 제공자를 씁니다. 한 번만 고를 때는 --local-provider ollama, 늘 쓰려면 설정 파일(config.toml)에 oss_provider = "ollama"를 둡니다. 모델 지정은 codex --oss -m gpt-oss:120b처럼 합니다. ollama launch codex --restore로 원래 설정을 되돌릴 수 있습니다.

✅ 연결이 제대로 동작하려면 필요한 조건

주소를 바꾼 것만으로는 에이전트가 제 역할을 하지 못합니다. 올라마 공식 문서가 공통으로 요구하는 조건은 두 가지입니다.

1. 도구 호출을 지원하는 모델: 에이전트는 모델이 "이 파일을 읽어라", "이 명령을 실행하라"는 도구 호출을 정해진 형식으로 내놓아야 움직입니다. 올라마 모델 검색의 tools 분류에서 고르고, 설치한 모델은 ollama show 모델이름의 Capabilities에 tools가 있는지 봅니다
2. 64,000토큰 이상의 컨텍스트: 에이전트는 파일 내용과 명령 결과를 계속 대화에 쌓습니다. 올라마 기본 컨텍스트는 GPU 메모리가 24GiB 미만이면 4k라서, 늘리지 않으면 몇 번 오가지 않아 앞 내용을 잊습니다. OLLAMA_CONTEXT_LENGTH=64000 ollama serve로 서버를 띄웁니다

올라마의 Anthropic 호환 문서는 로컬 권장 모델로 qwen3-coder와 gpt-oss:20b를 예로 듭니다. 컨텍스트를 64k로 늘리면 메모리도 그만큼 더 필요하므로, 모델 크기와 함께 따져 봐야 합니다.

⚠️ 공식 문서가 밝힌 한계

연결이 된다는 것과 원래 모델처럼 쓸 수 있다는 것은 다릅니다. 공식 문서에 적힌 한계부터 보면 이렇습니다.

• 앤트로픽의 입장: 클로드 코드 공식 문서는 서드파티 게이트웨이를 보증하지 않으며, 게이트웨이를 거쳐 Claude가 아닌 모델로 연결하는 것을 지원하지 않는다고 밝힙니다. 로컬 연결은 올라마 쪽 기능이고, 문제가 생겨도 클로드 코드의 지원 범위 밖입니다
• 빠지는 기능: 올라마 호환 API는 특정 도구 사용을 강제하는 tool_choice와 프롬프트 캐싱을 지원하지 않습니다. 클로드 코드의 웹 검색 기능도 완전히 지원되지 않고, 기본 주소가 아니면 Remote Control과 MCP 도구 검색이 꺼집니다
• 캐싱 부재의 영향: 에이전트는 매 요청마다 대화 전체를 다시 보내는데, 캐싱이 없으면 긴 대화일수록 입력 처리(프리필)에 시간이 계속 걸립니다
• 로그인 정보: ANTHROPIC_BASE_URL만 바꾸고 인증 값을 주지 않으면 저장된 claude.ai 로그인이 그대로 쓰입니다

속도의 한계는 기기에서 결정됩니다. 준이아빠블로그의 큐원 3.8 27B 맥 실측에서는 24GB 맥미니 M4 프로에 27B 모델(Q4_K_M)을 올렸더니 GPU 몫에 들어가지 않아 전부 CPU로 돌았고, 짧은 질문 하나에 218초, 생성 속도 초당 0.08토큰이 나왔습니다. 이 정도면 에이전트의 여러 차례 도구 호출을 기다릴 수 없습니다. 긴 입력을 자주 넣는 에이전트 작업은 생성 속도보다 입력 처리 속도가 먼저 걸린다는 사례도 DGX와 RTX 비교에 정리되어 있습니다. 모델 크기별로 필요한 메모리는 로컬 모델 크기 고르기에서 확인합니다.

🧭 로컬 연결을 쓰기 좋은 일

한계를 알고 쓰면 로컬 연결도 쓸모가 있습니다.

처음 연결했다면 결과를 눈으로 확인할 수 있는 작은 작업부터 맡겨 보고, 도구 호출이 몇 번째에서 어긋나는지 보는 편이 판단에 도움이 됩니다.

⚠️ 자주 하는 실수

• OpenAI 호환 주소를 클로드 코드에 넣습니다: http://localhost:11434/v1이 아니라 http://localhost:11434입니다
• 도구 호출을 지원하지 않는 모델을 고릅니다: 에이전트가 대화만 하고 파일을 고치지 못합니다
• 컨텍스트를 기본값으로 둡니다: 몇 차례 만에 앞의 지시를 잊습니다
• :cloud 태그 모델을 로컬로 착각합니다: 올라마 문서의 예시에는 클라우드 모델이 섞여 있고, 그 요청은 올라마 클라우드 서버로 나갑니다

❓ 자주 묻는 질문

로컬 모델로 바꾸면 클로드 코드 사용량 한도를 쓰지 않나요?

모델 요청이 내 컴퓨터로 가므로 앤트로픽 쪽 사용량은 쓰지 않습니다. 다만 인증 값을 주지 않고 주소만 바꿨다면 저장된 claude.ai 로그인이 그대로 쓰이므로, 올라마 문서처럼 인증 변수를 함께 설정하고 /status로 확인합니다.

어느 정도 기기면 에이전트용으로 쓸 만한가요?

공식 기준은 없습니다. 모델 전체가 GPU 메모리에 들어가고(ollama ps에서 100% GPU), 64k 컨텍스트까지 올린 상태에서도 그 조건이 유지되는지가 최소선입니다. 이 조건을 넘는 모델은 CPU로 밀려나 에이전트로 쓰기에는 너무 느려집니다.

코덱스와 클로드 코드 가운데 로컬 연결은 어느 쪽이 쉬운가요?

둘 다 ollama launch 한 줄로 연결됩니다. 코덱스는 --oss라는 로컬 전용 옵션이 공식 기능으로 있고, 클로드 코드는 올라마의 Anthropic 호환 API에 붙으며 앤트로픽은 이 방식을 지원하지 않는다는 점이 다릅니다.

📋 3줄 요약

1. 올라마는 ollama launch claude, ollama launch codex 명령으로 클로드 코드와 코덱스 CLI를 로컬 모델에 연결하고, 클로드 코드는 OpenAI 호환이 아니라 Anthropic 호환 API로 붙습니다.

2. 에이전트용 로컬 모델은 도구 호출을 지원해야 하고 컨텍스트를 64,000토큰 이상으로 잡아야 하며, 올라마 호환 API는 tool_choice와 프롬프트 캐싱을 지원하지 않습니다.

3. 앤트로픽은 Claude가 아닌 모델로의 연결을 지원하지 않는다고 밝히고 있어서, 로컬 연결은 짧은 수정과 오프라인 작업에 쓰고 긴 자율 작업은 원래 모델에 맡기는 편이 안전합니다.