에이전트 하네스란? 모델과 프레임워크 차이
에이전트 하네스는 모델을 에이전트로 바꾸는 주변 프로그램입니다. 호출 루프, 도구, 권한, 세션 상태를 관리하며 모델 및 프레임워크와 어떻게 다른지 설명합니다.
에이전트 하네스란 무엇인가
에이전트 하네스는 언어 모델을 감싸고 이를 에이전트로 전환하는 프로그램입니다. 이 프로그램은 모델을 지속적으로 호출하는 루프, 모델이 호출할 수 있는 도구 정의, 호출 실행 여부를 결정하는 권한 규칙, 턴 사이에도 유지되는 세션 상태, 그리고 작업이 수행되는 작업 디렉터리를 관리합니다. 이 하네스 내부의 모델은 교체 가능합니다.
마지막 문장을 기억해야 합니다. 모델 단독으로는 질문에 답하고 나면 사용자를 잊어버립니다. 반면 하네스는 모델에게 다음에 무엇을 할지 묻고, 모델이 요청한 명령을 실행하며, 그 결과를 다시 입력으로 제공한 뒤 다시 질문합니다. 사람들이 "에이전트"라고 말할 때 의미하는 것이 바로 이러한 반복 과정입니다. 주변 용어가 여전히 모호하다면, AI 에이전트, LLM, 어시스턴트의 차이를 통해 도구를 선택하기 전에 용어를 명확히 정리할 수 있습니다.
하네스는 모델이 아닙니다
벤더들이 두 가지를 하나의 브랜드 이름으로 출시하기 때문에 혼동이 발생합니다.
dsh와 DeepSeek는 서로 다른 제품입니다. 2026년 8월 13일 MIT 라이선스로 github.com/deepseek-ai/deepseek-harness에 공개된 DeepSeek Harness는 사용자의 머신에 설치하는 Node 프로그램입니다. DeepSeek 모델은 API(application programming interface)를 통해 제공되는 가중치 데이터입니다. dsh를 다른 벤더의 모델로 지정해도 정상적으로 작동하는데, 이는 하네스가 메시지를 받아 도구 호출을 반환하는 대상만 필요로 하기 때문입니다.
Claude Code와 Claude도 같은 쌍입니다. Claude Code는 하네스로, 루프, 권한 시스템, 파일 및 셸 도구를 갖춘 터미널 프로그램입니다. Claude는 이 프로그램이 기본적으로 호출하는 모델 제품군입니다. Codex와 Gemini CLI도 동일한 방식으로 구분됩니다.
이를 확실하게 구분하는 방법은 다음과 같습니다. 하네스를 설치하고 모델을 호출해 보십시오. 디스크에 버전이 존재하고 홈 디렉터리에 설정 파일이 있다면 그것은 하네스입니다. 그 설정 파일 내부에 deepseek-flash과 같은 문자열이 있다면, 그것이 바로 모델입니다.
실제로 루프가 하는 일
하네스 루프의 한 번의 순환은 다음과 같다. 천천히 읽어야 한다. 하네스 간 차이의 거의 대부분은 이 5단계 안에서 발생한다.
- 하네스가 지금까지의 대화와 도구 정의 목록을 모델에 보낸다.
- 모델이 텍스트로 응답하거나, 해당 도구 중 하나를 호출해 달라는 요청을 보낸다.
- 하네스가 권한 규칙에 따라 요청을 확인한 뒤 요청을 실행하거나, 중단하고 사용자에게 확인을 요청한다.
- 하네스가 도구를 실행하고 출력과 종료 코드를 수집한 뒤, 출력이 매우 길면 잘라낸다.
- 하네스가 그 결과를 대화에 추가하고 1단계로 돌아간다.
일상적인 사용에서 하네스 간 차이가 가장 크게 드러나는 부분은 3단계다. 모든 명령을 실행하기 전에 확인을 요청하는 하네스는 안전하지만 피로를 유발한다. 전혀 확인하지 않는 하네스는 결국 모델이 잘못 판단한 경로에서 파괴적인 명령을 실행하게 된다. Claude Code는 이 둘의 중간 설정을 지원한다. 확인 없이 실행할 명령의 allowlist를 지정하고, 그 외의 명령에는 프롬프트를 표시한다.
나머지 차이는 1단계에서 발생한다. 하네스는 이러한 요청마다 함께 전달되는 system prompt도 작성한다. Claude Code에서는 출력 스타일이 전송하는 system prompt를 편집하므로 이 설정을 직접 조정할 수 있으며, 그 결과 돌아오는 모든 응답이 달라진다. 대화는 매 순환마다 커지고 모델의 context window는 고정되어 있으므로, 하네스는 무엇을 삭제하고 무엇을 요약하며 무엇을 파일에 기록해 나중에 다시 읽을지 결정해야 한다. 동일한 모델을 구동하는 두 하네스가 서로 다른 작업 품질을 내는 주된 이유는 이 결정에 있다. 이 5단계가 여전히 추상적으로 느껴진다면, 직접 단순한 루프를 한 번 작성하는 것이 해결책이다. 바로 그 작업을 AI 에이전트 학습을 위한 단계별 경로에서 초기에 구축하게 된다.
이제 대부분의 하네스는 MCP (model context protocol)를 통해 외부 도구를 연결한다. MCP는 이를 지원하는 모든 하네스에 도구를 노출하는 표준이므로, 하나의 통합으로 여러 하네스에서 사용할 수 있다. VPS에서 MCP 서버 실행하기에서 이 부분을 다룬다. 웹 검색은 사람들이 보통 가장 먼저 추가하는 도구다. 에이전트가 사용자의 SearXNG 인스턴스를 가리키도록 설정하기를 사용하면 검색어를 제3자에게 보내지 않을 수 있으며, 이후 에이전트가 읽는 모든 페이지가 루프 내부로 들어오는 신뢰할 수 없는 입력이라는 점도 분명해진다.
에이전트 하네스와 에이전트 프레임워크
새로운 하네스가 나올 때마다 이 질문이 제기됩니다. 답변이 서로 다른 이유 중 하나는 공급업체마다 정의가 다르기 때문입니다. 다음 설명이 가장 일관되게 적용됩니다.
프레임워크는 가져와서 사용하는 라이브러리입니다. 프레임워크의 루프를 사용하거나 직접 작성하여 코드로 에이전트를 구성합니다. LangChain이 잘 알려진 예입니다. 구성 요소를 제공받고 코드로 에이전트를 조립합니다.
하네스는 실행하는 프로그램입니다. 루프는 이미 작성되어 있고 도구도 이미 존재하며 권한 모델에도 기본값이 있습니다. 첫 번째 명령으로 작동하는 에이전트를 얻고, 이후 설정을 조정합니다.
대개 설치 방식으로 구분할 수 있습니다. 설치한 다음 코드를 작성한다면 프레임워크입니다. 설치한 다음 대화한다면 하네스입니다.
경계가 실제로 논쟁의 대상이라는 점은 LangChain 자체 문서에서 가장 분명하게 드러납니다. 2026년 10월 기준으로 LangChain은 Deep Agents를 "에이전트 하네스"라고 부르는 동시에 "에이전트를 위한 LangChain의 핵심 구성 요소 위에 구축된 독립형 라이브러리"라고도 부릅니다. 한편 langchain-ai/deepagents 저장소는 스스로를 "기능이 모두 포함된 에이전트 하네스"라고 설명합니다. 두 설명 모두 타당합니다. Deep Agents는 가져와서 사용하는 Python SDK(소프트웨어 개발 키트)이므로 설치 방식에 따르면 라이브러리입니다. 동시에 충분한 기본 동작을 제공하므로 사람들이 하네스처럼 사용합니다. Microsoft는 2026년 7월 9일 Foundry Agent Service의 Hosted Agents를 일반 공급한다고 발표했습니다. 또한 2026년 7월 22일 게시물에서는 Microsoft Agent Framework Harness의 출시를 발표했습니다. 이는 이 용어가 이제 전문 용어가 아니라 제품 범주가 되었음을 보여줍니다.
대신 작업 방식을 더 잘 예측하는 질문을 하십시오. 루프를 직접 작성하면 루프를 직접 책임져야 합니다. 재시도, 컨텍스트 축소, 권한 요청, 수행된 작업의 기록도 직접 관리해야 합니다. 루프가 제품에 포함되어 있으면 이 모든 항목에 대한 다른 사람의 결정을 그대로 물려받습니다. 따라서 시작은 훨씬 빠르지만 나중에 변경하기는 더 어렵습니다.
채팅 창과 하네스의 차이
채팅 창과 하네스는 모두 모델의 출력을 보여 줍니다. 차이는 작업이 어느 컴퓨터에서 수행되는지에 있습니다. 채팅 창에서는 모델이 실행하는 코드가 공급업체의 샌드박스에서, 사용자가 업로드한 파일을 대상으로 실행됩니다. 하네스는 하네스를 시작한 컴퓨터에서 도구를 실행하며, 하네스를 시작한 사용자의 권한으로 실제 파일을 대상으로 실행하고, 해당 환경의 실제 자격 증명을 사용합니다.
이것이 두 문장으로 설명할 수 있는 하네스의 이점과 위험 전부입니다. 에이전트는 이제 실제로 작업을 수행할 수 있습니다. 동시에 작업을 삭제할 수도 있습니다.
실제로 실행되고 있는 하네스
이 목록의 기준일을 19 August 2026로 정한 데에는 이유가 있습니다. 이 분야는 매주 변하므로 어떤 정리도 빠르게 오래된 정보가 됩니다.
- Claude Code와 Codex는 벤더가 제공하는 하네스입니다. 터미널 우선으로 동작하고 기본적으로 각 벤더의 자체 모델에 연결되며, 권한 처리가 가장 잘 다듬어져 있습니다. Claude Code, Cursor, Codex와 Copilot 비교에서 이들을 자세히 설명합니다.
- DeepSeek Harness (
dsh)는 MIT 라이선스로 제공되며, 모든 것이 플러그인이라는 한 가지 개념을 중심으로 설계되었습니다. 따라서 모델, 도구, 세션, 샌드박스, 사용자 인터페이스를 모두 교체 가능한 구성 요소로 취급합니다. 설치하는 각 플러그인은 에이전트 자체의 권한으로 실행되므로, dsh 플러그인을 추가하기 전에 접근 가능한 범위 확인하기가 고정된 도구 집합을 사용하는 하네스에서보다 여기서 더 중요합니다. - Hermes는 Nous Research가 만든 제품으로, 코딩 도구라기보다 범용 자율 에이전트입니다. 2026년 2월에 MIT 라이선스로 릴리스되었으며, 기본 제공 저장소는 로컬에 있습니다. 메모리와 스킬은
~/.hermes아래의 파일로 저장되고, 세션 기록은 로컬 SQLite 데이터베이스에 저장됩니다. Mem0나 Hindsight 같은 선택적 외부 메모리 제공자를 활성화하면 이것이 전체 상황이 아닙니다. 2026년 10월 기준으로 Hermes 문서에는 활성화된 제공자가 각 응답 후 모든 대화 턴과 기본 제공 메모리에 기록된 모든 내용을 복사한 데이터를 받는다고 설명되어 있습니다. 따라서 데이터는 해당 제공자에도 저장됩니다. 하나를 활성화하기 전에 Hindsight와 Mem0 비교를 읽어 보는 것이 좋으며, VPS에서 Hermes 자체 호스팅하기에서 나머지 과정을 설명합니다. - Omnigent는 메타 하네스입니다. Claude Code와 Codex를 포함한 다른 하네스를 하나의 API 뒤에서 실행하며, 공유 세션, 지출 한도, 운영 체제 수준의 샌드박스를 제공합니다. 다중 에이전트 하네스로서의 Omnigent에서 이를 통해 얻는 이점을 설명합니다.
- OneCLI는 팀을 대상으로 하는 샌드박스 하네스입니다. 게이트웨이가 에이전트의 외부 요청에 자격 증명을 주입하는 구조이므로, 에이전트 자체는 실제 키를 볼 수 없습니다.
이 가운데 3개는 자주 같은 최종 후보 목록에 오르므로, 모델 결합 방식, 라이선스, 성숙도, 서버에서 실행하는 데 필요한 요소를 비교한 DeepSeek Harness, Claude Code와 Omnigent 나란히 비교를 읽어 볼 만합니다.
dsh 빠른 시작은 단일 명령이며, 이를 한 번 실행하는 것이 하네스가 무엇인지 확인하는 가장 빠른 방법입니다. 시스템에 Node.js가 설치되어 있어야 합니다.
npx @deepseek-ai/dsh web이 명령을 실행하면 http://127.0.0.1:3080에서 웹 UI(사용자 인터페이스)가 시작됩니다. 이를 신뢰하고 사용하기 전에 README를 읽어야 합니다. dsh은 자체적으로 개발자 프리뷰라고 설명하며 호환성을 깨는 변경이 있을 것이라고 명시합니다. 첫 번째 명령이 즉시 실패하거나 예상하지 못한 빌드를 가져오면, 정확한 dsh 버전을 고정하고 npx 캐시 삭제하기를 수행하면 대개 다시 진행할 수 있습니다. VPS에서 DeepSeek Harness 실행하기에서 서버 설치를 설명하며, 해당 주소가 127.0.0.1로 시작하는 이유에서 루프백 기본값을 설명합니다.
라우터는 하니스 상위에 위치합니다
모델 라우터는 하니스와 공급자 API 사이의 로컬 프록시 역할을 합니다. Claude Code Router가 대표적인 예시이며, 기본적으로 127.0.0.1:3456에 바인딩되어 Claude Code가 원래 공급자에게 보냈을 요청을 수신한 뒤, 사용자가 설정한 공급자에게 전달합니다. 하니스는 이러한 변경 사항을 전혀 알지 못합니다.
모델을 교체할 수 있어야 하므로 라우터가 존재하며, 이는 본 게시물의 핵심 요점을 입증하는 좋은 사례입니다. 또한 프록시가 모든 프롬프트를 확인하고 모든 공급자 키를 보유하므로 위험이 집중됩니다. 이를 단순한 편의 도구가 아닌 인프라로 취급해야 합니다. 하니스가 API 키와 모델 설정을 보관하는 위치는 한 단계 아래에서도 동일한 문제입니다.
하네스가 VPS에서 실행될 때 달라지는 점
하네스를 노트북에서 임대한 서버로 옮기면 4가지가 달라집니다.
노트북 덮개를 닫아도 계속 실행됩니다. 장시간 작업이 출퇴근과 배터리 상태의 영향을 받지 않습니다. tmux 안에서 시작한 다음 세션에서 분리합니다.
tmux new -s agent
# start the harness, then press Ctrl-b and then d to detach
tmux attach -t agent재부팅 후에도 다시 시작되어야 하는 작업에는 터미널 세션보다 사용자 서비스가 적합합니다.
loginctl enable-linger $USER
systemctl --user status my-agent.serviceloginctl enable-linger은 사람들이 자주 놓치는 부분입니다. 이 설정이 없으면 systemd는 마지막 세션이 닫힌 후 10초가 지나면 사용자의 서비스 관리자를 중지합니다. 따라서 사용자 서비스가 로그아웃 후에도 에이전트를 계속 실행하지 못합니다. systemd에서 헤드리스로 dsh 실행에 unit 파일이 있습니다. 해당 서버에서 하나의 세션이 실행 중이면 두 번째 세션을 시작할 수 있습니다. 또한 같은 서버에서 실행되는 두 Claude Code 세션은 서로 메시지를 보낼 수 있으므로, 오늘 아침에 시작한 세션이 사용자가 직접 전달하지 않아도 다른 세션에 작업을 넘길 수 있습니다.
키를 보관합니다. 이제 공급자 키가 해당 서버의 설정 파일에 저장됩니다. 누가 이 파일을 읽을 수 있는지 확인합니다.
ls -l ~/.config사용자로 실행되는 모든 프로세스가 이 파일을 읽을 수 있습니다. 여기에는 에이전트와 에이전트가 실행하기로 선택한 모든 항목이 포함됩니다.
다른 컴퓨터에 연결할 수 있습니다. 다른 서버와 동일한 사설 네트워크에 있는 VPS는 에이전트가 해당 서버에 연결할 수 있는 경로를 제공합니다. 이것이 바로 VPS를 사용하는 목적이며, 동시에 장애가 확산될 수 있는 범위이기도 합니다.
어디에서든 연결할 수 있습니다. 대부분의 하네스는 웹 UI를 제공하며, 대부분의 하네스가 웹 UI를 loopback에 바인딩하는 데는 이유가 있습니다. 현재 설정을 확인합니다.
ss -tlnp | grep 3080127.0.0.1:3080는 서버 자체만 연결할 수 있다는 뜻입니다. 0.0.0.0:3080는 UI가 모든 인터페이스에서 수신 대기한다는 뜻입니다. 따라서 앞단의 방화벽이 포트를 차단하지 않는 한 서버의 공인 주소에 연결할 수 있는 누구나 UI에 연결할 수 있습니다. 2026년 10월 현재 dsh은 시작 시 이와 같은 wildcard 주소를 거부합니다. 그러나 다른 웹 UI 중에는 이를 허용하는 것도 많습니다. 바인드 주소를 변경하지 말고 SSH 터널을 통해 loopback UI에 연결합니다.
ssh -N -L 3080:127.0.0.1:3080 you@your-server그런 다음 노트북의 브라우저에서 http://127.0.0.1:3080을 엽니다. 트래픽은 SSH 세션 내부를 통과하므로 인터넷에 새로 노출되는 항목이 없습니다.
이 모든 항목은 보안 측면에서도 동일하게 적용됩니다
공격자의 관점에서 앞서 언급한 네 가지 속성을 다시 살펴보십시오.
이 도구는 무인 상태로 실행되므로 모델이 경로를 잘못 해석하는 순간을 감시하는 사람이 없습니다. 또한 키를 보관하고 있으므로 읽기 가능한 설정 파일 하나가 곧 귀하의 전체 제공자 계정이 될 수 있습니다. 이 도구는 다른 머신에 접근할 수 있으므로, 웹 페이지나 에이전트가 읽는 파일에 숨겨진 지시 사항인 프롬프트 인젝션이 데이터베이스 호스트로 가는 경로를 열어줄 수 있습니다. 어디서든 접근이 가능하므로 방화벽이나 자체 인증 없이 공용 주소에서 대기하는 웹 UI는 이를 발견한 누구에게나 셸(shell)을 제공하는 꼴이 됩니다. dsh은 시작 시 출력하는 URL에 프로세스 토큰을 포함하는데, 이는 도움이 되지만 해당 URL 자체가 자격 증명이 되므로 비밀번호만큼이나 주의해서 공유해야 합니다.
각 사례에 대한 해결책은 지루하지만 매번 동일합니다. 에이전트에게 귀하의 계정이 아닌 권한이 제한된 별도의 사용자 계정을 부여하십시오.
sudo adduser --disabled-password --gecos "" agent웹 UI는 loopback 인터페이스에 유지하고 SSH를 통해 접근하십시오. 에이전트가 작업을 완료하는 데 필요한 최소한의 권한만 부여하십시오. 이에 관한 자세한 내용은 AI 에이전트에서 비밀 정보 보호하기에서 다룹니다. 감시하지 않는 동안 실행되는 모든 작업에는 꼼꼼하게 관리하는 머신보다 일회용 머신이 더 낫습니다. 일회용 VM에서 코딩 에이전트 실행하기와 VPS에서 안전하게 Claude Code 실행하기 모두 이러한 방식을 따릅니다.
에이전트 하네스가 필요합니까?
작업이 한 번에 하나의 질문으로 끝난다면 채팅 창으로 충분하며, 하네스는 감독해야 하는 루프만 추가합니다. 작업이 실제 파일을 대상으로 여러 단계를 거치거나, 사용자가 잠든 동안에도 계속 실행되어야 할 때 하네스는 비용 대비 효과를 내기 시작합니다.
이 범주의 대부분은 아직 초기 단계입니다. dsh는 2026년 10월 기준 자체 README에서 developer preview라고 밝히고 있으며, 나머지도 매우 빠르게 발전하므로 오늘 작성한 구성 파일을 다음 달에 수정해야 할 수 있습니다. 따라서 설정을 작고 재현 가능하게 유지하고, 변경한 내용을 기록해야 합니다. 같은 절제는 루프 내부에서도 도움이 됩니다. 에이전트가 작동하는 가장 작은 변경을 선택하도록 유도하는 skill을 사용하면, 사람이 지켜보지 않은 실행이 끝난 뒤에도 실제로 읽을 수 있는 diff가 남습니다. 서버 1대에 하네스 1개로 시작하고, 작업 1개와 범위가 좁은 key 1개만 부여하십시오. 첫 작업이 일주일 동안 지루할 정도로 안정적으로 끝난 뒤에만 접근 범위를 넓히십시오. 오늘 실행할 가치가 있는 self-hosted agent에서 첫 번째 대상을 선택하는 것도 합리적입니다.
FAQ
에이전트 하네스를 쉽게 말하면 무엇입니까?
모델을 둘러싼 프로그램입니다. 모델은 텍스트와 도구 사용 요청을 생성합니다. 하네스는 계속 요청을 보내는 루프를 실행하고, 모델이 요청한 도구를 실행하며, 어떤 도구를 허가 없이 실행할 수 있는지에 관한 규칙을 적용하고, 턴 사이에 세션 상태와 파일을 유지합니다. 모델을 바꿔도 하네스가 계속 작동한다는 점은 두 가지가 서로 별개라는 가장 분명한 증거입니다.
Claude Code는 모델입니까, 하네스입니까?
Claude Code는 하네스입니다. 루프, 권한 시스템, 파일 및 셸 도구를 내장한 터미널 프로그램입니다. Claude는 Claude Code가 기본적으로 호출하는 모델 제품군입니다. 같은 구분이 DeepSeek Harness(dsh)에도 적용됩니다. DeepSeek Harness는 설치하는 Node 프로그램이며, DeepSeek 모델은 API를 통해 제공됩니다. 하네스는 시스템에 설치합니다. 모델은 네트워크를 통해 호출합니다.
에이전트 하네스와 에이전트 프레임워크의 차이는 무엇입니까?
프레임워크는 가져와서 코드를 작성하는 라이브러리입니다. 프레임워크의 루프를 사용하거나 직접 작성합니다. 하네스는 실행하는 프로그램입니다. 따라서 루프, 재시도, 컨텍스트 처리가 직접 작성하는 대신 설정할 수 있는 기본값과 함께 제공됩니다. 실제로는 경계가 모호합니다. 2026년 10월 기준으로 LangChain의 Deep Agents는 가져올 수 있는 SDK이며, 자체 저장소에서는 이를 기능이 기본 제공되는 에이전트 하네스라고 부릅니다. 루프를 직접 작성하게 되는지 확인하면 됩니다. 그 답에 따라 현재 상황에 맞는 용어가 결정됩니다.
에이전트 하네스를 실행하려면 VPS가 필요합니까?
아니요. 여기서 언급한 모든 하네스는 노트북에서 실행됩니다. 서버를 사용하면 4가지가 달라집니다. 노트북 덮개를 닫아도 에이전트가 계속 실행되고, 항상 켜져 있는 시스템에 키를 보관할 수 있으며, 다른 서버에 접근할 수 있고, 어떤 장치에서든 같은 세션으로 돌아갈 수 있습니다. 이 네 가지는 모두 보안 고려 사항이기도 하므로 에이전트에 별도의 사용자 계정을 할당하고 웹 UI는 127.0.0.1에 바인딩해야 합니다.
같은 하네스에서 다른 모델을 사용할 수 있습니까?
대체로 가능합니다. 이것이 하네스의 정의상 핵심 특성입니다. 대부분의 하네스는 설정에서 모델 이름과 base URL을 지정하므로, 다른 provider를 가리키도록 수정하는 일은 다시 작성하는 것보다 간단합니다. 하네스가 이를 지원하지 않는 경우에는 Claude Code Router와 같은 로컬 라우터를 하네스와 provider 사이에 둘 수 있습니다. 이 라우터는 요청을 변환하며 기본적으로 127.0.0.1:3456에 바인딩합니다. 이 프록시는 모든 프롬프트를 보고 모든 키를 보관하므로 주의해야 합니다.