에이전트 하네스란 무엇인가: 모델과 하네스의 차이점

에이전트 하네스란 무엇인가

에이전트 하네스는 언어 모델을 감싸고 이를 에이전트로 전환하는 프로그램입니다. 이 프로그램은 모델을 지속적으로 호출하는 루프, 모델이 호출할 수 있는 도구 정의, 호출 실행 여부를 결정하는 권한 규칙, 턴 사이에도 유지되는 세션 상태, 그리고 작업이 수행되는 작업 디렉터리를 관리합니다. 이 하네스 내부의 모델은 교체 가능합니다.

마지막 문장을 기억해야 합니다. 모델 단독으로는 질문에 답하고 나면 사용자를 잊어버립니다. 반면 하네스는 모델에게 다음에 무엇을 할지 묻고, 모델이 요청한 명령을 실행하며, 그 결과를 다시 입력으로 제공한 뒤 다시 질문합니다. 사람들이 "에이전트"라고 말할 때 의미하는 것이 바로 이러한 반복 과정입니다. 주변 용어가 여전히 모호하다면, AI 에이전트, LLM, 어시스턴트의 차이를 통해 도구를 선택하기 전에 용어를 명확히 정리할 수 있습니다.

하네스는 모델이 아닙니다

공급업체가 두 가지를 하나의 브랜드 이름으로 출시하기 때문에 혼동이 발생합니다.

dsh와 DeepSeek는 서로 다른 제품입니다. 2026년 8월 13일 github.com/deepseek-ai/deepseek-harness에 MIT 라이선스로 공개된 DeepSeek Harness는 사용자의 머신에 설치하는 Node 프로그램입니다. DeepSeek 모델은 API(application programming interface)를 통해 제공되는 가중치 데이터입니다. dsh를 다른 공급업체의 모델로 지정해도 정상적으로 작동하는데, 이는 하네스가 메시지를 수신하고 도구 호출을 반환하는 기능만 필요로 하기 때문입니다.

Claude Code와 Claude도 같은 쌍입니다. Claude Code는 하네스로서, 루프와 권한 시스템, 파일 및 셸 도구를 갖춘 터미널 프로그램입니다. Claude는 이 프로그램이 기본적으로 호출하는 모델 제품군입니다. Codex와 Gemini CLI도 동일한 방식으로 구분됩니다.

이를 항상 명확하게 구분할 수 있는 테스트 방법이 있습니다. 하네스는 설치하는 대상입니다. 모델은 호출하는 대상입니다. 디스크에 버전이 존재하고 홈 디렉터리에 설정 파일이 있다면 그것은 하네스입니다. 그 설정 파일 내부에 deepseek-chat과 같은 문자열로 적혀 있다면 그것이 모델입니다.

루프의 실제 동작 방식

하네스 루프의 한 주기는 다음과 같이 동작합니다. 하네스마다 차이가 발생하는 지점은 대부분 이 다섯 단계 내부에 있으므로 천천히 읽어 보시기 바랍니다.

1. 하네스는 지금까지의 대화 내용과 도구 정의 목록을 모델에 전달합니다.
2. 모델은 텍스트로 응답하거나, 도구 호출을 요청합니다.
3. 하네스는 해당 요청이 권한 규칙에 부합하는지 확인한 뒤, 실행하거나 사용자에게 확인을 요청하며 멈춥니다.
4. 하네스는 도구를 실행하고 출력 결과와 종료 코드를 캡처하며, 결과가 너무 길면 이를 자릅니다.
5. 하네스는 해당 결과를 대화 내용에 추가하고 1단계로 돌아갑니다.

3단계는 일상적인 사용에서 하네스 간의 차이가 가장 크게 드러나는 부분입니다. 모든 명령마다 확인을 요청하는 하네스는 안전하지만 피로도가 높습니다. 반대로 확인 절차가 전혀 없는 하네스는 모델이 잘못 판단한 경로에서 결국 파괴적인 명령을 실행하게 됩니다. 현재 대부분의 전문적인 하네스는 중간 설정을 제공합니다. 즉, 확인 없이 실행할 명령의 허용 목록(allowlist)을 관리하고, 그 외의 모든 명령에 대해서는 사용자에게 확인을 구합니다.

나머지 차이점은 대부분 1단계에서 발생합니다. 하네스는 모든 요청에 포함되는 시스템 프롬프트를 작성합니다. Claude Code는 출력 스타일이 시스템 프롬프트를 수정하는 방식을 통해 사용자가 직접 이 설정을 조정할 수 있게 하며, 이를 통해 돌아오는 모든 응답의 형태가 바뀝니다. 대화가 진행될수록 내용은 길어지지만 모델의 컨텍스트 윈도우는 고정되어 있으므로, 하네스는 무엇을 삭제하고 무엇을 요약하며, 무엇을 파일로 기록했다가 나중에 다시 읽을지 결정해야 합니다. 동일한 모델을 사용하더라도 하네스에 따라 작업 품질이 달라지는 주된 이유가 바로 이 결정 과정에 있습니다. 이 다섯 단계가 여전히 추상적으로 느껴진다면, 직접 간단한 루프를 작성해 보는 것이 가장 좋은 해결책입니다. 이는 AI 에이전트 학습을 위한 단계별 경로에서 초기에 수행하는 작업이기도 합니다.

현재 대부분의 하네스는 MCP(model context protocol)를 통해 외부 도구를 연결합니다. 이는 도구를 해당 프로토콜을 지원하는 모든 하네스에 노출하는 표준 방식이므로, 한 번의 통합으로 여러 하네스에서 도구를 사용할 수 있습니다. VPS에서 MCP 서버 실행하기에서 이와 관련된 내용을 다룹니다. 웹 검색은 보통 가장 먼저 추가하는 도구이며, 에이전트를 자신의 SearXNG 인스턴스에 연결하면 제3자에게 쿼리가 노출되는 것을 방지할 수 있습니다. 다만, 이때 에이전트가 읽어 들이는 모든 페이지는 루프 내부로 유입되는 신뢰할 수 없는 입력값이라는 점을 명심해야 합니다.

에이전트 하니스(harness)와 에이전트 프레임워크(framework)

새로운 하니스가 등장할 때마다 이 질문이 제기되지만, 공급업체마다 의견이 달라 답변도 일관되지 않습니다. 다음은 가장 타당한 구분 방식입니다.

프레임워크는 사용자가 임포트(import)하여 사용하는 라이브러리입니다. 사용자가 루프를 작성하고, 모델 호출 시점을 결정하며, 도구 실행 결과를 직접 처리합니다. LangChain이 잘 알려진 예시입니다. 빌딩 블록을 제공받아 코드로 에이전트를 조립하는 방식입니다.

하니스는 실행 가능한 프로그램입니다. 루프는 이미 작성되어 있고, 도구는 준비되어 있으며, 권한 모델에는 기본값이 설정되어 있습니다. 첫 번째 명령어를 입력하는 즉시 작동하는 에이전트를 얻게 되며, 이후 설정을 조정합니다.

설치 후 테스트 과정이 보통 이를 결정합니다. 설치 후 코드를 작성해야 한다면 프레임워크입니다. 설치 후 바로 대화를 시작할 수 있다면 하니스입니다.

이 경계는 실제로 논쟁의 여지가 많으며, 가장 명확한 증거는 LangChain 자체 문서에서 찾을 수 있습니다. 2026년 8월 기준으로 LangChain 문서는 Deep Agents를 LangGraph 기반의 "독단적이고 모든 기능을 갖춘(opinionated, batteries-included)" 프레임워크로 설명하는 반면, langchain-ai/deepagents 저장소는 스스로를 "모든 기능을 갖춘 에이전트 하니스"라고 부릅니다. 두 설명 모두 타당합니다. Deep Agents는 임포트하여 사용하는 Python SDK(software development kit)이므로 설치 테스트 기준으로는 라이브러리이지만, 기본 동작을 충분히 내장하고 있어 사람들이 하니스처럼 사용하기도 합니다. Microsoft는 2026년 8월에 하니스와 호스팅된 에이전트를 정식 출시(general availability)했으며, 이는 이제 이 용어가 전문 용어를 넘어 하나의 제품 범주로 자리 잡았음을 보여줍니다.

따라서 작업 부하를 예측할 수 있는 질문을 던져보십시오. 루프를 직접 작성한다면 재시도, 컨텍스트 트리밍, 권한 프롬프트, 작업 기록 등 루프에 대한 모든 책임은 사용자에게 있습니다. 반면 루프가 내장된 제품을 사용한다면, 해당 문제들에 대한 타인의 해결 방식을 그대로 따르게 됩니다. 이는 시작하기에는 훨씬 빠르지만, 나중에 변경하기는 더 어렵습니다. 다만 내장 루프를 쓰더라도 에이전트가 같은 실수를 반복할 때 프롬프트를 고쳐 쓰는 대신 CLAUDE.md, 훅, CI 같은 주변 환경을 손보는 하네스 엔지니어링으로 그 기본 동작을 상당 부분 자신의 프로젝트에 맞출 수 있습니다.

Harness와 채팅 창의 차이점

채팅 창과 Harness는 모두 모델의 출력 결과를 보여준다는 점은 같습니다. 차이점은 작업이 수행되는 컴퓨터가 어디인가 하는 것입니다. 채팅 창에서 모델이 실행하는 모든 코드는 벤더의 샌드박스 내부에서, 사용자가 업로드한 파일에 대해 실행되며 세션이 종료되면 사라집니다. 반면 Harness는 사용자가 시작한 머신에서, 해당 머신의 사용자 권한으로, 실제 파일과 환경 내의 실제 자격 증명을 사용하여 도구를 실행합니다.

이 두 문장이 이 방식의 모든 장점이자 모든 위험 요소입니다. 에이전트가 비로소 실제 작업을 수행할 수 있게 되지만, 동시에 에이전트가 작업을 삭제할 수도 있다는 뜻입니다.

실제로 사용되는 하네스

이 목록은 의도적으로 2026년 8월 19일 기준으로 작성되었습니다. 이 분야는 매주 변화하므로 모든 요약 정보는 빠르게 구식이 됩니다.

• Claude Code와 Codex는 벤더 제공 하네스입니다. 터미널 중심이며 기본적으로 해당 벤더의 모델에 고정되어 있고, 가장 세련된 권한 관리 기능을 제공합니다. Claude Code, Cursor, Codex 및 Copilot 비교에서 이들을 자세히 다룹니다.
• DeepSeek Harness (dsh)는 MIT 라이선스를 따르며 '모든 것은 플러그인이다'라는 철학으로 구축되었습니다. 따라서 모델, 도구, 세션, 샌드박스, 사용자 인터페이스를 모두 교체할 수 있습니다. 설치하는 각 플러그인은 에이전트의 권한으로 실행되므로, dsh 플러그인 추가 전 접근 권한 확인하기가 고정된 도구 세트를 사용하는 하네스보다 훨씬 중요합니다. 이 도구는 출시 6일 후인 2026년 8월 19일 기준으로 약 166,800개의 GitHub 스타를 기록했습니다.
• Hermes는 Nous Research에서 개발한 범용 자율 에이전트로, 코딩 도구에 국한되지 않습니다. 2026년 2월 MIT 라이선스로 출시되었으며, 기억과 기술을 사용자 기기의 로컬 SQLite 데이터베이스에 저장합니다. 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(사용자 인터페이스)를 시작합니다. dsh는 개발자 프리뷰 버전이며 호환성을 깨뜨리는 변경 사항이 발생할 수 있다고 명시하고 있으므로, 사용하기 전에 README를 반드시 읽어보십시오. 첫 번째 명령이 즉시 실패하거나 예상치 못한 빌드를 가져오는 경우, 특정 dsh 버전 고정 및 npx 캐시 삭제를 통해 문제를 해결할 수 있습니다. VPS에서 DeepSeek Harness 실행하기는 서버 설치를 다루며, 주소가 127.0.0.1로 시작하는 이유에서는 루프백 기본값에 대해 설명합니다.

라우터는 하니스 상위에 위치합니다

모델 라우터는 하니스와 공급자 API 사이의 로컬 프록시 역할을 합니다. Claude Code Router가 대표적인 예시이며, 기본적으로 127.0.0.1:3456에 바인딩되어 Claude Code가 원래 공급자에게 보냈을 요청을 수신한 뒤, 사용자가 설정한 공급자에게 전달합니다. 하니스는 이러한 변경 사항을 전혀 알지 못합니다.

모델을 교체할 수 있어야 하므로 라우터가 존재하며, 이는 본 게시물의 핵심 요점을 입증하는 좋은 사례입니다. 또한 프록시가 모든 프롬프트를 확인하고 모든 공급자 키를 보유하므로 위험이 집중됩니다. 이를 단순한 편의 도구가 아닌 인프라로 취급해야 합니다. 하니스가 API 키와 모델 설정을 보관하는 위치는 한 단계 아래에서도 동일한 문제입니다.

하네스를 VPS에서 실행할 때 달라지는 점

하네스를 개인 노트북에서 임대 서버로 옮기면 네 가지가 달라집니다.

노트북 덮개를 닫아도 계속 실행됩니다. 긴 작업은 출퇴근 시간이나 배터리 상태와 관계없이 유지됩니다. 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.service

loginctl enable-linger은 사람들이 자주 놓치는 부분입니다. 이 설정이 없으면 마지막 SSH (secure shell) 세션이 종료되는 즉시 systemd가 사용자 서비스를 중단하므로, 로그아웃 시 에이전트가 종료되어도 오류 메시지가 출력되지 않습니다. systemd에서 dsh를 헤드리스로 실행하기에 유닛 파일이 있습니다. 서버에 세션 하나가 유지되고 있다면 두 번째 세션을 추가하는 데 드는 비용은 없으며, 같은 서버에서 두 개의 Claude Code 세션은 서로 메시지를 주고받을 수 있습니다. 따라서 아침에 시작한 세션이 직접 중계할 필요 없이 다른 세션으로 작업을 넘길 수 있습니다.

키를 서버에 보관합니다. 이제 공급자 키가 서버의 설정 파일에 저장됩니다. 읽기 권한을 확인하십시오:

ls -l ~/.config

사용자 계정으로 실행되는 모든 프로세스는 해당 파일을 읽을 수 있으며, 여기에는 에이전트와 에이전트가 실행하기로 선택한 모든 작업이 포함됩니다.

다른 장비에 접근할 수 있습니다. 다른 장비와 같은 사설 네트워크에 있는 VPS는 에이전트에게 해당 장비로 가는 경로를 제공합니다. 이것이 바로 핵심 목적이지만, 동시에 영향 범위이기도 합니다.

어디서든 접근할 수 있습니다. 대부분의 하네스는 웹 UI를 노출하며, 대부분 루프백 주소에 바인딩하는 데에는 이유가 있습니다. 설정을 확인하십시오:

ss -tlnp | grep 3080

127.0.0.1:3080는 서버 자체에서만 연결할 수 있음을 의미합니다. 0.0.0.0:3080은 주소를 아는 누구나 연결할 수 있음을 의미합니다. 바인딩 주소를 변경하는 대신 SSH 터널을 통해 루프백 UI에 접근하십시오:

ssh -N -L 3080:127.0.0.1:3080 you@your-server

그런 다음 노트북 브라우저에서 http://127.0.0.1:3080을 여십시오. 트래픽은 SSH 세션 내부를 통과하므로 인터넷에 새로운 내용이 노출되지 않습니다.

이 모든 요소는 보안 측면에서도 중요한 근거가 됩니다

공격자의 관점에서 앞서 언급한 네 가지 속성을 다시 살펴보십시오.

이 에이전트는 무인으로 실행되므로 모델이 경로를 잘못 해석하는 순간을 감시하는 사람이 없습니다. 에이전트는 사용자의 키를 보유하고 있으므로, 읽기 가능한 설정 파일 하나가 곧 전체 제공업체 계정의 권한을 의미하게 됩니다. 또한 에이전트는 다른 시스템에 접근할 수 있으므로, 웹 페이지나 에이전트가 읽는 파일에 숨겨진 지시 사항인 프롬프트 인젝션이 발생하면 데이터베이스 호스트로 향하는 경로가 열리게 됩니다. 어디서든 접근이 가능하므로 비밀번호 없이 0.0.0.0에 바인딩된 웹 UI는 공용 인터넷에 노출된 셸과 다름없습니다.

각 사례에 대한 해결책은 지루하지만 매번 동일합니다. 에이전트에게 사용자의 계정이 아닌, 권한이 제한된 별도의 사용자 계정을 할당하십시오.

sudo adduser --disabled-password --gecos "" agent

웹 UI는 루프백 인터페이스에 유지하고 SSH를 통해 접근하십시오. 에이전트가 작업을 완료하는 데 필요한 최소한의 권한만 부여해야 하며, 이에 대한 자세한 내용은 AI 에이전트에서 비밀 정보 제외하기에서 다룹니다. 사용자가 지켜보지 않는 동안 실행되는 모든 작업에는 꼼꼼하게 관리하는 시스템보다 일회용 시스템이 더 효과적입니다. 일회용 VM에서 코딩 에이전트 실행하기와 VPS에서 안전하게 Claude Code 실행하기가 모두 이러한 방식을 따릅니다.

에이전트 하네스가 필요한가?

작업이 한 번에 하나의 질문을 처리하는 방식이라면 채팅 창만으로도 충분하며, 하네스는 오히려 감독해야 할 루프만 추가할 뿐입니다. 하네스는 실제 파일들을 대상으로 여러 단계를 거쳐야 하는 작업을 수행하거나, 사용자가 잠든 사이에도 계속 작동해야 할 때 비로소 가치를 발휘합니다.

이 범주의 도구들은 대부분 초기 단계입니다. dsh은 2026년 8월 기준으로 README에 개발자 프리뷰라고 명시되어 있으며, 나머지 도구들도 빠르게 변화하고 있어 오늘 작성한 설정 파일이 다음 달에는 수정이 필요할 수 있습니다. 이러한 이유로 설정을 작고 재현 가능하게 유지하고, 변경 사항을 기록해 두어야 합니다. 이러한 절제는 루프 내부에서도 도움이 되며, 작동하는 가장 작은 변경 사항으로 에이전트를 유도하는 기술을 사용하면 무인 실행이 끝난 후 실제로 읽을 수 있는 diff를 얻을 수 있습니다. 하나의 서버에서 하나의 하네스로 시작하여 하나의 작업과 제한된 권한의 키를 부여하십시오. 그 첫 번째 작업이 일주일 동안 아무 문제 없이 지루하게 느껴질 때 비로소 접근 권한을 넓히는 것이 좋습니다. 오늘 바로 실행해 볼 만한 셀프 호스팅 에이전트는 첫 번째 도구를 선택하기에 적절한 참고 자료입니다.

FAQ

에이전트 하니스(agent harness)란 무엇인가요?

모델을 감싸고 있는 프로그램을 의미합니다. 모델은 텍스트를 생성하고 도구 사용을 요청합니다. 하니스는 모델이 요청한 도구를 실행하고, 허가 없이 실행 가능한 도구에 대한 규칙을 강제하며, 세션 상태와 파일 변경 사항을 턴(turn) 사이에 유지하는 루프를 구동합니다. 모델을 교체해도 하니스가 그대로 작동한다면, 이는 두 요소가 명확히 분리되어 있다는 가장 확실한 증거입니다.

Claude Code는 모델인가요, 하니스인가요?

Claude Code는 하니스입니다. 루프, 권한 시스템, 내장 파일 및 셸 도구를 갖춘 터미널 프로그램입니다. Claude는 이 프로그램이 기본적으로 호출하는 모델 제품군입니다. 동일한 구분 방식이 DeepSeek Harness(dsh)에도 적용됩니다. 이는 사용자가 설치하는 Node 프로그램이며, DeepSeek 모델은 API를 통해 서비스됩니다. 하니스는 로컬 머신에 설치하고, 모델은 네트워크를 통해 호출합니다.

에이전트 하니스와 에이전트 프레임워크의 차이점은 무엇인가요?

프레임워크는 라이브러리 형태로 가져와서 코드를 작성하는 대상이므로, 루프, 재시도, 컨텍스트 처리를 직접 구현해야 합니다. 하니스는 실행 가능한 프로그램이므로, 이러한 기능이 기본값으로 제공되며 코드를 작성하는 대신 설정을 변경하여 사용합니다. 실제로는 이 경계가 모호합니다. 2026년 8월 기준으로 LangChain의 Deep Agents는 가져오기 가능한 SDK이지만, 해당 저장소에서는 이를 '배터리 포함형 에이전트 하니스'라고 부릅니다. 루프를 직접 작성해야 하는지 자문해 보십시오. 그 답변에 따라 적절한 용어가 결정됩니다.

에이전트 하니스를 실행하려면 VPS가 필요한가요?

아닙니다. 여기에 언급된 모든 하니스는 노트북에서도 실행됩니다. 서버를 사용하면 네 가지가 달라집니다. 노트북 덮개를 닫아도 에이전트가 계속 실행되고, 항상 켜져 있는 머신에 키를 보관하며, 다른 서버에 접근할 수 있고, 어떤 기기에서든 동일한 세션으로 돌아올 수 있습니다. 이 각각은 보안 고려 사항이기도 하므로, 에이전트 전용 사용자 계정을 생성하고 웹 UI는 127.0.0.1에 바인딩하십시오.

같은 하니스 안에서 다른 모델을 사용할 수 있나요?

대개 가능하며, 이것이 하니스의 핵심적인 특징입니다. 대부분 설정 파일에서 모델 이름과 기본 URL을 지정할 수 있으므로, 다른 제공업체로 연결하는 것은 코드 재작성이 아닌 설정 수정으로 가능합니다. 하니스가 이를 지원하지 않는 경우, Claude Code Router와 같은 로컬 라우터를 하니스와 제공업체 사이에 두어 요청을 변환할 수 있으며, 기본적으로 127.0.0.1:3456에 바인딩됩니다. 이 프록시는 모든 프롬프트와 키를 볼 수 있으므로 주의해서 사용해야 합니다.