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

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

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

마지막 문장이 가장 중요합니다. 모델 단독으로는 질문에 답한 뒤 사용자를 잊어버립니다. 반면 하니스는 모델에 다음 행동을 묻고, 모델이 요청한 명령을 실행한 뒤, 그 결과를 다시 입력하여 다음 단계를 질문합니다. 사람들이 "에이전트"라고 말할 때 의미하는 것이 바로 이러한 반복 과정입니다. 관련 용어가 여전히 모호하다면, 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과 같은 문자열이 들어 있다면, 그것이 바로 모델입니다.

루프의 실제 동작 방식

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

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

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

나머지 차이점은 1단계에서 발생합니다. 대화는 루프가 돌 때마다 길어지지만 모델의 컨텍스트 윈도우는 고정되어 있습니다. 따라서 하네스는 무엇을 삭제하고, 무엇을 요약하며, 무엇을 파일로 기록했다가 나중에 다시 읽어올지 결정해야 합니다. 동일한 모델을 사용하더라도 하네스에 따라 작업 품질이 달라지는 주된 이유가 바로 이 결정 과정에 있습니다.

최근 대부분의 하네스는 MCP(model context protocol)를 통해 외부 도구를 연결합니다. 이는 도구를 지원하는 모든 하네스에 노출할 수 있는 표준 방식이므로, 한 번의 통합으로 여러 하네스에서 도구를 사용할 수 있습니다. VPS에서 MCP 서버 실행하기에서 이와 관련된 내용을 다룹니다.

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

새로운 하니스가 출시될 때마다 이 질문이 제기되지만, 공급업체마다 의견이 달라 답변도 제각각입니다. 다음은 가장 타당한 구분 기준입니다.

프레임워크는 사용자가 임포트하여 사용하는 라이브러리입니다. 사용자가 직접 루프를 작성하고, 모델 호출 시점을 결정하며, 도구 실행 결과를 직접 처리합니다. LangChain이 대표적인 예로, 빌딩 블록을 조합하여 코드로 에이전트를 구성합니다.

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

설치 후 테스트 과정이 이를 결정짓는 기준이 됩니다. 설치 후 코드를 작성해야 한다면 프레임워크이고, 설치 후 바로 대화할 수 있다면 하니스입니다.

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

따라서 작업 부하를 예측할 수 있는 질문을 던져야 합니다. 루프를 직접 작성한다면 재시도, 컨텍스트 트리밍, 권한 프롬프트, 작업 기록 등 루프에 대한 모든 책임을 사용자가 집니다. 반면 제공되는 루프를 사용한다면 그 모든 문제에 대해 타인이 내린 결정을 그대로 따르게 되며, 이는 시작은 훨씬 빠르지만 나중에 변경하기는 더 어렵습니다.

하네스와 채팅 창의 차이점

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

이 두 문장이 하네스의 모든 장점과 위험을 요약합니다. 에이전트가 비로소 실제 작업을 수행할 수 있게 되지만, 동시에 에이전트가 작업을 삭제할 수도 있다는 의미입니다.

실제로 사용되는 하네스(Harness)

이 목록은 의도적으로 2026년 8월 19일 기준으로 작성되었습니다. 해당 분야는 매주 변화하고 있으며, 어떤 요약본이든 금방 구식이 되기 때문입니다.

• Claude Code와 Codex는 벤더 제공 하네스입니다. 터미널 중심이며 기본적으로 해당 벤더의 모델에 연결되어 있고, 가장 세련된 권한 처리 기능을 갖추고 있습니다. Claude Code, Cursor, Codex 및 Copilot 비교에서 이들을 상세히 다룹니다.
• DeepSeek Harness (dsh)는 MIT 라이선스를 따르며 한 가지 아이디어를 바탕으로 구축되었습니다. 모든 것이 플러그인이라는 점입니다. 따라서 모델, 도구, 세션, 샌드박스, 사용자 인터페이스를 모두 교체할 수 있습니다. 2026년 8월 19일 기준으로, 출시 6일 만에 약 166,800개의 GitHub 스타를 기록했습니다.
• Hermes는 Nous Research에서 개발했으며, 코딩 도구라기보다는 범용 자율 에이전트에 가깝습니다. 2026년 2월 MIT 라이선스로 출시되었으며, 기억과 기술을 사용자 로컬 머신의 SQLite 데이터베이스에 저장합니다. VPS에서 Hermes 자가 호스팅하기에서 관련 내용을 안내합니다.
• Omnigent는 메타 하네스입니다. Claude Code와 Codex를 포함한 다른 하네스들을 하나의 API 뒤에서 구동하며, 세션 공유, 지출 한도 설정, 운영체제 수준의 샌드박스를 제공합니다. 멀티 에이전트 하네스로서의 Omnigent에서 이 도구의 이점을 설명합니다.
• OneCLI는 팀을 겨냥한 샌드박스형 하네스입니다. 아웃바운드 요청에 실제 자격 증명을 주입하는 게이트웨이를 중심으로 구축되어, 에이전트 자체는 항상 자리 표시자(placeholder) 키만 볼 수 있도록 설계되었습니다.

dsh 퀵 스타트는 단일 명령어로 실행되며, 한 번 실행해보는 것이 하네스가 무엇인지 파악하는 가장 빠른 방법입니다. 머신에 Node.js가 설치되어 있어야 합니다.

npx @deepseek-ai/dsh web

이 명령을 실행하면 http://127.0.0.1:3080에서 웹 UI(사용자 인터페이스)가 시작됩니다. dsh는 개발자 프리뷰 버전이며 호환성을 깨뜨리는 변경 사항이 있을 것임을 명시하고 있으므로, 사용하기 전에 README를 읽어보시기 바랍니다. 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는 에이전트에게 해당 장비들로 향하는 경로를 제공합니다. 이것이 바로 VPS를 사용하는 이유이지만, 동시에 보안 영향 범위(blast radius)이기도 합니다.

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

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 세션 내부를 통해 전달되므로 인터넷에 새로운 포트가 노출되지 않습니다.

이 모든 속성은 보안 측면에서도 동일하게 적용됩니다

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

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

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

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

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

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

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

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

FAQ

에이전트 하니스(agent harness)란 무엇입니까?

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

Claude Code는 모델입니까, 하니스입니까?

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

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

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

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

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

동일한 하니스 안에서 다른 모델을 사용할 수 있습니까?

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