에이전트 하네스(agent harness)란 무엇이며, OpenClaw는 무엇을 하는가

언어 모델(language model) 자체는 텍스트만 생성할 수 있습니다. 파일을 열거나, 명령어를 실행하거나, API를 호출하거나, 5분 전에 무엇을 했는지 기억할 수 없습니다. 에이전트 하네스(agent harness)는 그 간극을 메워주는 계층입니다. 모델의 텍스트 출력을 받아 이를 실제 행동(이 파일 읽기, 이 명령어 실행, 이 폴더 검색)으로 전환하고, 그 결과를 모델에 다시 전달하며, 작업이 완료될 때까지 루프(loop)를 반복합니다. 모델이 두뇌라면, 하네스는 손입니다.

OpenClaw는 이러한 하네스 중 하나이며, 현재 가장 널리 사용되고 있습니다. 불과 몇 달 만에 방대한 설치 기반을 확보했으며 에이전트 사용량 차트의 최상단에 위치하고 있습니다. 당신이 일상 언어로 목표를 제시하면, OpenClaw는 계획을 세우고, 도구(tools)를 호출하며, 결과를 보고합니다. OpenClaw는 OpenAI 호환 API(OpenAI-compatible API)를 노출하는 모든 모델과 통신할 수 있는데, 이것이 이 가이드에서 중요한 세부 사항입니다. 즉, 특정 클라우드 벤더에 종속되지 않는다는 것입니다. 당신의 로컬 머신에서 실행 중인 모델을 포함하여, 원하는 어떤 모델 엔드포인트(endpoint)로든 지정할 수 있습니다.

이것이 바로 여기서 말하고자 하는 핵심 아이디어입니다. 에이전트 루프(agent loop)를 위한 OpenClaw, 모델을 위한 QVAC, 그리고 두 가지 모두 당신이 제어하는 하드웨어에서 실행하는 것입니다.

// Detect dark theme var iframe = document.getElementById('tweet-2067624599270166813-984'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2067624599270166813&theme=dark" }

사람들이 OpenClaw를 사용하는 용도

하네스는 범용적이므로 사용 사례가 매우 광범위합니다. 일반적인 사례는 다음과 같습니다:

• 코딩 작업 (Coding tasks). 저장소(repo)를 읽고, 함수를 작성하고, 테스트를 실행하며, 고장 난 부분을 수정합니다. 에이전트는 파일을 편집하고 명령어를 직접 실행합니다.
• 파일 및 시스템 잡무 (File and system chores). 일괄 파일 이름 변경, 문서 폴더 요약, 디렉토리 재구성, 스프레드시트에서 숫자 추출 등을 수행합니다.
• 로컬 조사 및 초안 작성 (Local research and drafting). 일련의 노트를 읽고 요약본, 초안 또는 구조화된 표를 생성합니다.
• 글루 워크 (Glue work). 생성하고, 저장하고, 열고, 이동하는 것과 같이 수동으로 수행해야 할 몇 가지 단계를 하나로 연결합니다.
• 상시 가동 어시스턴트 (Always-on assistants). 항상 켜져 있는 소형 기기에서 실행하고, 노트북이나 휴대폰으로 접속합니다.

이 모든 사례에서 에이전트는 실제 파일과 실제 시스템에 대해 동작을 수행합니다. 이것이 바로 모델이 어디에서 실행되는지가 중요해지는 이유입니다.

에이전트에게 로컬 AI가 올바른 기본값인 이유

모델이 채팅만 할 때는 모델이 어디에서 실행되는지가 주로 프라이버시(privacy)의 문제입니다. 하지만 모델이 사용자의 파일을 읽고 명령어를 실행하는 에이전트를 구동할 때는 제어(control)의 문제가 됩니다. 에이전트는 사용자의 기기에서 동작하며, 만약 그 배후의 모델이 타인의 데이터 센터(datacenter)에 있다면, 모델이 읽는 모든 파일과 실행하는 모든 명령어는 사용자가 소유하지 않은 시스템, 즉 해당 시스템의 가동 시간(uptime), 지연 시간(latency), 약관(terms), 그리고 액세스 정책(access policy)에 의존하게 됩니다. 이러한 요소들은 사용자 모르게 언제든 변경될 수 있습니다. 모델을 로컬에서 실행하면 에이전트는 속도를 제한하거나, 변경하거나, 차단할 수 있는 서비스가 아니라 사용자의 하드웨어에 종속되도록 유지할 수 있습니다.

모델을 로컬에서 실행하는 것은 단순히 정책을 바꾸는 것이 아니라 속성(property) 자체를 변화시킵니다:

• 데이터가 기기에 머뭅니다. 에이전트가 읽는 파일, 작성하는 코드, 실행하는 명령 중 그 어떤 것도 모델에 도달하기 위해 사용자의 디스크를 떠나지 않습니다. 사용자가 확인할 수 없는 서버에 프롬프트 로그(prompt log)가 남지 않습니다.
• 오프라인에서 작동합니다. 모델을 한 번 다운로드하면 완전히 연결을 끊어도 에이전트는 계속 작동합니다. 비행기 모드를 켜고 질문을 던져보세요. 여전히 답변합니다.
• 토큰당 비용이 발생하지 않습니다. 모델은 이미 소유하고 있는 하드웨어에서 실행됩니다. 사용량에 따라 비용이 부과되는 API를 사용할 때라면 실제 돈이 들었을 긴 에이전트 세션도 로컬에서는 비용이 전혀 들지 않습니다. 또한, 대규모 추론(inference) 서비스를 위한 비용 상승으로 인해 시간이 지남에 따라 청구 금액이 불어날 위험도 없습니다.
• 조용한 모델 교체가 없습니다. 가중치(weights)는 사용자의 디스크에 있는 파일입니다. 일부 제공업체가 비용을 절감하기 위해 사용하는 방식처럼, 세션 사이에 사용자가 모르는 사이 모델이 바뀌지 않습니다.

그 대가는 지연 시간(latency)과 원시 성능(raw capability)입니다. 노트북에 들어가는 모델은 프런티어 클라우드 모델(frontier cloud model)보다 크기가 작으므로, 더 느리고 정교함이 떨어집니다. 하지만 광범위한 실제 업무 영역에서 이러한 트레이드오프(trade-off)는 충분히 가치가 있으며, 소형 모델들이 발전함에 따라 성능은 계속해서 좋아지고 있습니다.

QVAC는 로컬 환경을 실용적으로 만들어주는 핵심 요소입니다. 이는 Tether에서 제공하는 오픈 소스 SDK 및 CLI로, 모든 주요 GPU 백엔드(NVIDIA, AMD, Intel, Linux/Windows/Android의 Vulkan을 통한 Adreno (Qualcomm) 및 Mali, 그리고 Metal을 통한 Apple Silicon)에서 사용자의 기기 상에 모델을 실행하며, OpenAI 호환 서버를 함께 제공합니다. 이 서버는 OpenClaw가 연결되는 가교 역할을 합니다.

작동 방식

세 가지 구성 요소가 있으며, 그중 두 가지는 계속 실행 상태를 유지합니다:

1. QVAC 서버는 모델을 메모리에 유지하며, 사용자의 로컬 포트에서 OpenAI 호환 요청에 응답합니다. 한 번 실행하면 계속 켜두면 됩니다.
2. OpenClaw 게이트웨이는 에이전트 루프(agent loop)를 실행합니다. 설정 중에 QVAC 서버를 가리키도록 지정한 다음, 이 역시 계속 실행 상태로 둡니다.
3. 사용자의 명령은 게이트웨이로 전달됩니다. 질문을 하거나 작업을 맡기면, 에이전트는 로컬 모델을 대상으로 작업을 수행합니다.

이 체인 내의 어떤 요소도 추론 (Inference)을 위해 인터넷을 호출하지 않습니다. 모델 파일은 한 번 다운로드되면, 그 이후의 모든 과정은 기기 내부에서 이루어집니다.

어떤 모델을 실행할 것인가

이 설정은 대부분의 노트북에서 가장 균형 잡힌 성능을 보여주는 Qwen3-8B를 사용합니다. 메모리가 부족하다면 4B 모델로 낮추십시오. 만약 워크스테이션을 보유하고 있으며 다단계 코딩 작업에서 더 강력한 결과를 원한다면, Qwen3.6-27B 멀티모달 (Multimodal) 모델로 업그레이드하십시오. 모델을 전환하려면 설정 파일(설정 단계 2)의 모델 이름을 마지막 열의 상수(Constant)로 변경하면 됩니다.

GPU가 있으면 큰 도움이 되지만 필수 사항은 아닙니다. QVAC는 Apple Silicon에서는 Apple Metal을 사용하고, NVIDIA, AMD, Intel에서는 Vulkan을 사용합니다. CPU 전용 기기에서도 실행은 가능하지만 속도가 더 느립니다. qvac doctor를 실행하여 귀하의 하드웨어가 무엇을 지원하는지 확인하십시오.

설정하기

아래의 가이드는 그대로 복사하여 붙여넣기만 하면 됩니다. 각 단계를 순서대로 실행하면 몇 분 안에 로컬 코딩 에이전트 (Coding Agent)를 갖게 될 것입니다. 실제로 시간이 걸리는 유일한 작업은 첫 번째 모델 다운로드입니다. 설정에는 4비트로 양자화된 (Quantized) Qwen3-8B(약 4.7 GB)가 사용되며, 이는 한 번 다운로드되면 이후에는 캐시 (Cache)됩니다.

두 가지 경로가 있으며, 아래 단계는 두 경우를 모두 처리합니다:

• 아직 OpenClaw가 없다면, 선택 사항인 설치 단계를 실행하십시오.
• 이미 OpenClaw를 가지고 있다면, 해당 단계를 건너뛰십시오. 나머지는 모두 동일합니다.

요구 사항: Node.js 22.17 이상 (node --version으로 확인, nodejs.org에서 설치). 모델을 위한 약 5 GB의 여유 디스크 공간.

1. QVAC CLI 설치 (모든 플랫폼)

npm install -g @qvac/cli @qvac/sdk

2. 모델 설정 생성. 폴더를 만들고 하나의 작은 설정 파일을 작성합니다.

macOS 및 Linux:

mkdir -p ~/qvac-openclaw && cd ~/qvac-openclaw
cat > qvac.config.json <<'EOF'
{
...

Windows (PowerShell):

mkdir $HOME\qvac-openclaw; cd $HOME\qvac-openclaw
@'
{
...

3. QVAC 서버 시작 (모든 플랫폼). 해당 폴더에서 실행하고 터미널을 열어둔 상태로 유지하세요. qwen3-8B-Q4-chat은 2단계에서 정의한 별칭(alias)이며, Qwen3-8B 모델을 4비트 (Q4_K_M)로 제공합니다. 첫 실행 시 모델을 한 번 다운로드합니다 (약 4.7 GB). QVAC API server listening 메시지가 보이면 준비된 것입니다.

qvac serve openai --model qwen3-8B-Q4-chat

4. OpenClaw 설치 (선택 사항). 이미 설치되어 있다면 건너뛰세요.

npm install -g openclaw

5. OpenClaw를 QVAC로 연결 (새 터미널). 첫 번째 명령은 OpenClaw를 로컬 서버에 연결합니다. 다음 세 개의 명령은 로컬 모델에서 에이전트가 빠르고 안정적으로 작동하도록 유지합니다.

openclaw onboard --auth-choice custom-api-key --custom-base-url http://127.0.0.1:11434/v1 --custom-model-id qwen3-8B-Q4-chat --custom-api-key "qvac" --non-interactive --accept-risk --skip-channels --skip-daemon --skip-search --skip-ui --skip-skills --skip-health

여기서 두 가지 값은 2단계와 연결됩니다. --custom-model-id qwen3-8B-Q4-chat은 설정 파일의 모델 별칭(serve.models 아래의 키)과 일치해야 합니다. --custom-api-key "qvac"는 자리 표시자(placeholder)일 뿐입니다. 로컬 QVAC 서버는 키를 요구하지 않지만, OpenClaw의 설정 과정에서 해당 필드가 채워져 있어야 하므로 비어 있지 않은 어떤 값이라도 상관없습니다.

openclaw config set tools.profile coding
openclaw config set tools.allow '["write","read","exec"]' --strict-json
openclaw config set models.providers.custom-127-0-0-1-11434.timeoutSeconds 600

6. 에이전트 게이트웨이(agent gateway) 시작 (새 터미널, 열어둔 상태로 유지). ready가 보이면 준비된 것입니다.

openclaw gateway run

7. 로컬 에이전트와 대화하기 (새 터미널). 네트워크를 끄고 다시 질문해 보세요.

openclaw agent --agent main --message "Are you running in the cloud or on my machine? Answer in one sentence."

8. 무언가를 구축하도록 시키기 (선택 사항). 에이전트에게 작은 애니메이션 웹 페이지를 작성하고 이를 열도록 요청합니다. 로컬 모델에서는 1~2분 정도 소요됩니다. open 명령어는 플랫폼마다 다릅니다: macOS는 open, Linux는 xdg-open, Windows는 start를 사용합니다.

openclaw agent --agent main --message "Create an HTML file at ~/openclaw_lobster.html showing a large lobster emoji at 140px pulsing with a CSS scale animation on a dark #0f1410 background, with the text 'openclaw running on local with QVAC' in teal #16E3C1 monospace below it, fully visible immediately. Then run the shell command: open ~/openclaw_lobster.html"

방금 구축한 것, 그리고 다음에 시도해 볼 것

이제 여러분의 기기에서 완전히 실행되는 코딩 에이전트(coding agent)를 갖게 되었습니다. 첫 번째 테스트로 명확한 사실을 확인해 보는 것이 좋습니다. 에이전트에게 클라우드에서 실행 중인지 아니면 여러분의 기기에서 실행 중인지 물어본 다음, 네트워크를 끄고 다시 물어보세요. 에이전트는 계속해서 답변할 것입니다. 왜냐하면 애초에 서버로 전송되는 데이터가 전혀 없었기 때문입니다.

눈으로 확인할 수 있는 것을 원한다면, 작은 구축 작업(build task)을 맡기고 에이전트가 파일을 작성하고 여는 과정을 지켜보세요. 작은 웹 페이지를 생성하는 것과 같은 코딩 작업은 일반적인 노트북에서 완전히 오프라인 상태로 1~2분 내에 실행됩니다. 모델이 데이터 센터(datacenter)로부터 스트리밍하는 대신 로컬에서 실제 작업을 수행하기 때문입니다. 이 설정에는 바로 사용할 수 있는 예시가 포함되어 있습니다. 여러분의 추가 입력 없이도 에이전트가 아주 작은 애니메이션 웹 페이지를 작성하고 브라우저에서 열도록 요청합니다.

여기서부터는 동일한 설정으로 OpenClaw가 수행하는 나머지 작업들을 처리할 수 있습니다. 프로젝트 폴더를 지정하고, 코드를 읽고 편집하도록 요청하거나, 디렉터리를 요약하게 하거나, 여러 단계의 잡무를 맡겨보세요. 에이전트 루프(agent loop)는 동일합니다. 유일하게 바뀐 점은 그 뒤에 있는 지능(intelligence)이 여러분의 것이라는 점뿐입니다.

참고 사항 및 제한 사항

• 노트북에 들어가는 모델은 프론티어 클라우드 모델 (frontier cloud model)이 아닙니다. 속도가 더 느리고 더 명확한 지시 사항이 필요할 것임을 예상하십시오. 에이전트 (agent) 작업의 경우, 길고 개방적인 작업보다는 집중된 단일 목표 작업을 부여하십시오.
• 하드웨어에 따라 로컬 응답은 현재 클라우드 API보다 더 오래 걸릴 수 있습니다. 이를 영구적인 비용이 아닌 일시적인 격차로 간주하십시오. 로컬 하드웨어는 계속해서 빨라지고 있으며, 성능을 유지하면서도 모델은 계속해서 작아지고 있으므로 그 격차는 빠르게 좁혀지고 있습니다. 물리 법칙 또한 로컬에 유리하게 작용합니다. 데이터 센터로의 요청은 빛의 속도에 의해 제한되며, 이는 어떤 제공업체도 기술적으로 해결할 수 없는 왕복 시간 (round trip)입니다. 로봇, 제어 루프 (control loop), 라이브 인터페이스와 같이 실시간으로 반응해야 하는 모든 작업에서 이 왕복 시간은 물리적인 하한선이며, 로컬은 신뢰성을 유지할 수 있는 유일한 옵션입니다.
• QVAC는 Apache 2.0 라이선스이며 무료입니다. 실행하는 모델은 한 번 다운로드되어 로컬에 캐시 (cached)됩니다. 소스 및 문서: github.com/tetherto/qvac 및 docs.qvac.tether.io.