오픈소스 AI 에이전트 하네스란? 로컬 모델로 에이전트를 돌리는 도구 고르는 법
오픈소스 AI 에이전트 하네스의 개념과, OpenCode·goose·Aider·OpenHands를 Ollama 같은 로컬 모델에 연결할 때 볼 컨텍스트 길이·도구 호출·라이선스·보안 기준을 정리했어요.
목차7개 섹션
핵심 요약
- 에이전트 하네스는 모델 자체가 아니라, 모델에 도구 목록을 주고 호출 결과를 다시 넣어 주는 반복 루프·권한·파일 접근을 담당하는 실행 틀이에요.
- 로컬 모델 서버(Ollama·LM Studio·llama.cpp 등)와 하네스는 보통 OpenAI 호환 API로 연결되며, 두 계층을 따로 골라야 해요.
- Ollama는 VRAM 24GiB 미만에서 기본 컨텍스트가 4k라서, 공식 문서는 에이전트·코딩 도구에 최소 64000토큰을 권장해요(2026년 10월 기준).
- 도구 호출을 제대로 못 하는 모델을 붙이면 하네스가 일반 챗봇처럼 동작할 수 있어요. 모델 선택이 하네스 선택만큼 중요해요.
- 라이선스는 하네스(OpenCode MIT, goose Apache-2.0)와 모델 가중치 라이선스를 따로 확인해야 해요.
- 셸 실행·파일 수정 권한은 기본 승인 모드로 두고, 작업 폴더를 제한하거나 컨테이너 안에서 돌리는 편이 안전해요.
오픈소스 AI 에이전트 하네스는 언어 모델을 도구 호출·파일 접근·반복 실행 루프로 감싸서, 모델이 답변만 하는 대신 파일을 읽고 명령을 실행하고 결과를 확인하며 작업을 끝까지 진행하게 만드는 실행 틀이에요. 로컬 모델로 에이전트를 돌리려면 모델 서버(Ollama·LM Studio·llama.cpp 등)와 하네스(OpenCode·goose·Aider·OpenHands 등)를 따로 고르고, 둘을 연결할 때 컨텍스트 길이와 도구 호출 지원을 맞추는 것이 핵심이에요. 이 글은 2026년 10월 기준 각 프로젝트의 공식 문서를 확인해 정리했어요.
검색창에 'open source ai agents', 'open source ai harness', 'models to run locally'가 함께 뜨는 이유도 여기에 있어요. 좋은 모델만 받아서는 에이전트가 되지 않고, 어떤 하네스에 어떤 설정으로 붙이느냐에 따라 같은 모델이 유능한 작업자가 되기도 하고 도구를 못 쓰는 챗봇이 되기도 해요.
오픈소스 AI 에이전트 하네스는 무엇을 하나요
하네스의 기본 동작은 단순해요. 사용자 요청과 사용 가능한 도구 목록을 모델에 보내고, 모델이 도구 호출을 돌려주면 하네스가 실제로 그 도구를 실행한 뒤 결과를 대화에 덧붙여 다시 모델에 보내요. 모델이 더 이상 도구를 부르지 않을 때 루프가 끝나요. Ollama 도구 호출 문서는 이 구조를 'Agent loop'라는 이름으로 예제와 함께 설명하고 있어요.
즉 모델은 '무엇을 할지' 결정하고, 하네스는 '실제로 실행하고 안전하게 통제하는' 역할을 맡아요. 그래서 하네스를 고를 때는 모델 성능보다 아래 기능을 먼저 비교하게 돼요.
- 도구 세트: 파일 읽기·쓰기·편집, 셸 실행, 검색, 웹 가져오기 등 기본 제공 도구의 범위
- 권한 모델: 파일 수정이나 셸 실행 전에 승인을 받는지, 읽기 전용 모드가 있는지
- 확장성: MCP(Model Context Protocol) 서버 연결, 사용자 정의 도구·에이전트 지원 여부
- 모델 연결 방식: Ollama 전용인지, OpenAI 호환 API라면 어디든 붙는지
- 인터페이스: 터미널(TUI/CLI), 데스크톱 앱, 웹 UI, API 중 무엇을 쓰는지
모델 서버와 하네스는 다른 계층이에요
Ollama·LM Studio·llama.cpp·vLLM은 모델을 메모리에 올려 API로 응답을 내주는 추론 서버예요. 하네스는 그 API를 호출하는 클라이언트이고요. 대부분 OpenAI 호환 엔드포인트(예: http://localhost:11434/v1)로 연결되기 때문에, 서버를 바꿔도 하네스 설정의 주소와 모델 ID만 고치면 되는 경우가 많아요. 반대로 도구를 실제로 실행하는 곳은 하네스가 돌아가는 컴퓨터라는 점을 기억해야 보안 설정을 제대로 할 수 있어요.
대표 하네스 비교: 로컬 AI 모델 연결 방식과 라이선스
아래 표는 2026년 10월 기준 각 프로젝트의 공식 문서와 저장소에서 확인한 내용만 담았어요. 라이선스는 저장소에 표시된 값이며, 확인하지 못한 항목은 비워 두지 않고 '저장소에서 확인'으로 표시했어요.
OpenCode
- 형태
- 터미널 TUI·데스크톱 앱·CLI
- 로컬 모델 연결
- Ollama·LM Studio·llama.cpp 제공자, OpenAI 호환 사용자 정의 제공자
- 라이선스
- MIT
- 눈여겨볼 점
- build(전체 권한)·plan(읽기 전용) 에이전트 전환
goose
- 형태
- 데스크톱 앱·CLI·API(Rust)
- 로컬 모델 연결
- Ollama 포함 15개 이상 제공자
- 라이선스
- Apache-2.0
- 눈여겨볼 점
- MCP로 70개 이상 확장 연결, 리눅스 재단 AAIF 소속
Aider
- 형태
- 터미널 페어 프로그래밍
- 로컬 모델 연결
- ollama_chat/ 접두사로 Ollama 연결
- 라이선스
- 저장소에서 확인
- 눈여겨볼 점
- 요청 크기+응답 8k에 맞춰 Ollama 컨텍스트를 자동 설정
OpenHands
- 형태
- Docker 기반 웹 UI
- 로컬 모델 연결
- LM Studio·Ollama·vLLM·SGLang의 OpenAI 호환 엔드포인트
- 라이선스
- 저장소에서 확인
- 눈여겨볼 점
- 컨텍스트 최소 22000, 권장 32768 안내
OpenCode
OpenCode 제공자 문서에 따르면 AI SDK와 Models.dev를 이용해 75개 이상의 제공자를 지원하고 로컬 모델 실행도 지원해요. 목록에 없는 로컬 서버는 @ai-sdk/openai-compatible 패키지와 baseURL로 사용자 정의 제공자를 만들면 되고, 모델 ID는 서버의 GET /v1/models 응답과 같아야 해요. 문서는 도구 호출이 잘 안 되면 Qwen-Coder나 DeepSeek-Coder 계열처럼 도구 호출에 강한 모델을 고르라고 조언해요. 저장소에는 MIT 라이선스와 함께, 파일 편집을 기본 거부하고 bash 실행 전 승인을 받는 plan 에이전트가 소개돼 있어요.
goose
goose 저장소는 goose를 코드뿐 아니라 리서치·글쓰기·자동화에도 쓰는 범용 에이전트로 소개해요. macOS·Linux·Windows용 데스크톱 앱, CLI, API를 제공하고 Ollama를 포함한 15개 이상 제공자에 연결돼요. 2026년 10월 기준 저장소는 aaif-goose 조직으로 옮겨졌고, 리눅스 재단 산하 Agentic AI Foundation(AAIF) 프로젝트로 표시돼 있어요. 터미널이 낯선 사용자라면 데스크톱 앱이 있다는 점이 장점이에요.
Aider와 OpenHands
Aider의 Ollama 문서는 ollama/보다 ollama_chat/ 접두사를 권장하고, Ollama가 창을 넘는 컨텍스트를 조용히 버린다는 점을 경고해요. 그래서 Aider는 요청 크기에 응답용 8k 토큰을 더해 컨텍스트 창을 자동으로 잡아 줘요. OpenHands 로컬 LLM 문서는 Docker 컨테이너에서 실행되는 구조라, 호스트의 모델 서버에 host.docker.internal 주소로 접근하는 설정과 리눅스에서 바인드 주소를 바꿔야 하는 경우를 따로 안내해요.
로컬 모델 연결 전 확인할 사양: 컨텍스트 길이가 먼저예요
로컬 에이전트가 실패하는 가장 흔한 원인은 모델 크기보다 컨텍스트 길이 설정이에요. Ollama 컨텍스트 길이 문서에 따르면 기본값은 VRAM에 따라 달라져요.
| GPU VRAM | Ollama 기본 컨텍스트 |
|---|---|
| 24GiB 미만 | 4k |
| 24~48GiB | 32k |
| 48GiB 이상 | 256k |
같은 문서는 웹 검색·에이전트·코딩 도구처럼 큰 컨텍스트가 필요한 작업은 최소 64000토큰으로 설정하라고 권해요. 다만 컨텍스트를 늘리면 필요한 메모리도 늘어나므로, ollama ps의 PROCESSOR 열에서 모델이 100% GPU에 올라가 있는지, 일부가 CPU로 밀려났는지 확인해야 해요. CPU로 넘어가면 속도가 크게 떨어져 에이전트 루프가 답답해져요.
하네스마다 권장값이 달라요. Ollama 문서는 에이전트용으로 64000토큰 이상을, OpenHands 문서는 최소 22000·권장 32768을 제시해요. 어느 쪽이든 VRAM 24GiB 미만 환경의 Ollama 기본값(4k)은 에이전트에 부족하므로 직접 늘려야 해요.
하드웨어 기준을 감으로 정하지 마세요
OpenHands 문서는 첫 로컬 모델로 Qwen3.6-35B-A3B를 권하면서, 양자화 버전에 VRAM 24GB 이상 GPU 또는 통합 메모리 64GB 이상의 Apple Silicon Mac이 필요하다고 적고 있어요. 이보다 낮은 사양이라면 더 작은 모델을 쓰게 되는데, 같은 문서의 커뮤니티 메모처럼 일부 로컬 모델은 컨텍스트가 넉넉해도 도구 호출을 안정적으로 못 할 수 있어요. 특정 모델의 파일 크기와 양자화 선택은 별도 가이드에서 다루는 편이 정확해요.
실제로 고르는 순서
- 1
용도부터 정해요
코드 수정이 주 목적이면 OpenCode·Aider·OpenHands, 문서 정리·자동화처럼 범용 작업이면 goose처럼 범용성을 내세우는 하네스가 출발점이에요. 터미널·데스크톱·웹 UI 중 익숙한 인터페이스도 함께 고려해요.
- 2
모델 서버를 고르고 컨텍스트를 맞춰요
Ollama라면
OLLAMA_CONTEXT_LENGTH나 앱 설정으로 컨텍스트를 늘리고ollama ps로 GPU 적재를 확인해요. LM Studio는 모델 로드 시 컨텍스트 길이를 직접 지정해요. - 3
도구 호출 지원 모델을 골라요
Ollama 문서 예제처럼 도구 호출을 지원하는 모델이어야 루프가 돌아요. 하네스 문서가 추천하는 모델이나 코딩 특화 모델로 먼저 시작하고, 작은 작업으로 파일 읽기·편집·명령 실행이 실제로 되는지 확인해요.
- 4
라이선스를 두 번 확인해요
하네스의 라이선스(예: OpenCode MIT, goose Apache-2.0)와 모델 가중치의 라이선스는 별개예요. 회사 업무나 상업적 사용이라면 모델 카드의 이용 조건까지 확인해요.
- 5
권한과 격리를 먼저 설정해요
셸 실행과 파일 수정은 승인 모드로 두고, 처음에는 읽기 전용 모드(OpenCode의 plan 등)로 동작을 관찰해요. 중요한 저장소는 별도 브랜치나 컨테이너에서 실험해요.
보안과 비용에서 놓치기 쉬운 점
- 셸 권한은 내 계정 권한이에요: 하네스가 실행하는 명령은 하네스를 띄운 사용자 권한으로 돌아요. 자동 승인 모드는 편하지만 잘못된 명령이 그대로 실행될 수 있어요.
- '로컬'이 곧 '오프라인'은 아니에요: OpenCode 문서는 세션 제목 생성 등 보조 작업용 small model이 기본으로 호스팅 모델을 쓴다고 안내하고, 고정하려면
small_model지정과share비활성화를 권해요. 웹 도구와 MCP 확장도 외부 네트워크를 써요. - 네트워크 노출 주의: OpenHands 문서처럼 Docker에서 접근하려고 모델 서버를
0.0.0.0에 바인드하면 같은 네트워크의 다른 기기에서도 접근할 수 있어요. 필요한 경우에만 열고 방화벽을 확인해요. - 비용은 전기·하드웨어로 옮겨 가요: 토큰 요금은 없지만 큰 컨텍스트와 긴 루프는 GPU 메모리와 시간을 많이 써요. 클라우드 모델과 로컬 모델을 작업별로 나눠 쓰는 하네스도 많아요.
새로운 오픈소스 에이전트와 모델은 매주 쏟아지기 때문에, 어떤 도구가 실제로 언급되는지 흐름을 함께 보는 것도 도움이 돼요. 더따리의 AI 텔레그램 트렌드와 블로그 대시보드에서 최근 화제가 되는 AI 도구 이야기를 모아 볼 수 있어요.
정리하면, 하네스는 '루프·도구·권한'을, 모델 서버는 '추론'을 맡아요. 용도에 맞는 하네스를 고르고, 컨텍스트 길이와 도구 호출 지원 모델을 맞춘 뒤, 승인 모드와 작업 폴더 제한부터 걸어 두면 로컬 모델로도 안정적으로 에이전트를 돌릴 수 있어요.
