에이전트 하네스
에이전트 하네스(harness)는 언어 모델에 대화 이력, 프로젝트 파일, 도구 설명을 제공하고, 모델이 요청한 도구를 실행하여 결과를 다시 전달하는 실행 환경입니다. 에이전트의 판단과 실행을 반복하는 루프를 실제 프로그램으로 구현합니다. Claude Code CLI, Codex CLI, OpenCode는 파일 탐색, 코드 편집, 터미널 명령 실행을 제공하는 코드 에이전트 하네스입니다.
1구성 요소¶
| 구성 요소 | 역할 | 예시 |
|---|---|---|
| 하네스 | 맥락 구성, 도구 실행, 권한 확인, 결과 전달 | Claude Code CLI, Codex CLI, OpenCode |
| 추론 서버 | 모델 적재, 토큰 생성, API 요청과 응답 처리 | Ollama, vLLM |
| 모델 | 입력 해석, 답변 생성, 도구 이름과 인수 선택 | 도구 호출을 학습한 코드·언어 모델 |
하네스가 추론 서버에 도구 정의와 대화를 보내면, 모델은 답변 또는 도구 호출을 생성합니다. 서버가 도구 호출을 API 형식으로 반환하면 하네스가 권한을 확인하고 도구를 실행합니다. 파일 편집과 셸 명령은 하네스가 실행되는 환경에 적용됩니다. 추론 서버가 원격에 있다는 이유로 도구도 그 서버에서 실행되지는 않습니다. 예를 들어 BIG의 컨테이너 안에서 하네스를 실행하면 작업 파일과 도구 실행 환경도 그 컨테이너를 기준으로 합니다.
2API 호환 형식¶
OpenAI 호환이라는 표현만으로 연결 가능 여부를 판단할 수 없습니다. Chat Completions와 Responses는 서로 다른 요청·응답 및 스트리밍 형식을 사용합니다. Claude Code에는 Anthropic Messages 호환 API가 필요합니다.
| 하네스 | 추론 서버 | 사용 API | 클라이언트의 기본 주소 예시 | 공식 안내 |
|---|---|---|---|---|
| Claude Code CLI | Ollama | Anthropic Messages | http://127.0.0.1:11434 | Ollama 연결 안내 |
| Claude Code CLI | vLLM | Anthropic Messages | http://127.0.0.1:8000 | vLLM 연결 안내 |
| Codex CLI | Ollama | OpenAI Responses | http://127.0.0.1:11434/v1 | Ollama 연결 안내 |
| Codex CLI | vLLM | OpenAI Responses | http://127.0.0.1:8000/v1 | vLLM 연결 안내 |
| OpenCode | Ollama | OpenAI Chat Completions | http://127.0.0.1:11434/v1 | Ollama 연결 안내 |
| OpenCode | vLLM | OpenAI Chat Completions | http://127.0.0.1:8000/v1 | OpenCode 사용자 정의 공급자 |
Claude Code의 기본 주소에는 /v1/messages를 붙이지 않습니다. 클라이언트가 경로를 추가합니다.
Codex의 base_url과 아래 OpenCode 공급자의 baseURL에는 /v1까지 지정합니다.
OpenCode와 vLLM의 조합은 전용 통합 공급자가 아니라 OpenCode의 사용자 정의 OpenAI 호환 공급자로 구성합니다.
전용 통합 문서에서 검증된 조합과 같은 의미로 해석해서는 안 됩니다.
3설치 환경¶
하네스는 작업 저장소에 접근할 수 있는 Linux 환경이나 컨테이너에 설치합니다. 다음은 설치 명령의 예시이며, 각 명령은 해당 하네스를 사용할 환경에서 한 번만 실행합니다. Node.js와 npm의 요구 버전, 운영체제 지원 범위는 설치 시점의 공식 문서를 따릅니다.
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode-ai하네스 설치 명령 예시
Claude Code 설치, Codex CLI 설치, OpenCode 설치에서 바이너리 설치 등의 대안도 제공합니다.
Claude Code의 npm 패키지도 플랫폼별 네이티브 바이너리를 설치합니다.
OpenCode의 위 명령과 opencode.json 예시는 공식 문서의 OpenCode 1 기준입니다. OpenCode 2 설치와 실행 파일이 충돌하거나 대체될 수 있으므로 서로 다른 세대의 설정을 혼용하지 않습니다.
서버 설치와 GPU·컨테이너 준비는 Ollama, vLLM을 따릅니다. 이하 예시는 Bash 계열 셸 기준이며, 하네스에서 서버의 루프백 주소에 접근할 수 있는 구성을 가정합니다. 클라이언트와 서버가 서로 다른 컨테이너나 호스트에 있으면 원격 연결의 주소 구성이 필요합니다.
3.1Ollama 실행 도우미의 사전 조건¶
ollama launch는 Ollama v0.15.0 릴리스에 추가되었습니다.
Ollama CLI와 접근 가능한 Ollama 서버, 도구 호출 모델을 준비하고 작업 프로젝트 디렉터리에서 실행합니다.
하네스 실행 파일도 실행 도우미와 같은 환경에서 사용할 수 있어야 합니다.
공식 빠른 시작은 Codex CLI의 사전 설치를 요구하며, Claude Code와 OpenCode가 없으면 설치를 제안한다고 설명합니다.
설치가 제한된 환경에서는 하네스를 미리 준비하고 설치 제안을 실행하지 않습니다.
launch 도입 버전과 개별 옵션·구성 방식의 지원 시작 버전은 구분합니다.
아래 옵션은 현재 CLI 문서와 하네스별 문서에 명시된 동작이며, 문서에 각 옵션의 최초 지원 버전은 없습니다.
설치된 CLI의 ollama launch --help와 해당 버전 문서를 확인하고 모든 옵션이 v0.15.0부터 동일했다고 가정하지 않습니다.
자동 구성은 하네스별 설정이나 생성 파일에 영향을 줄 수 있으므로 기존 설정과 구성 우선순위를 확인합니다.
로컬 추론이 목적이면 앞에서 만든 coding-64k처럼 서버에 준비된 로컬 모델을 선택합니다.
선택 목록의 클라우드 모델은 외부에서 추론됩니다.
OpenCode Zen은 별도의 선택 가능한 모델 게이트웨이이며 로컬 서버 연결에 필요하지 않습니다.
4모델과 도구 호출¶
코드를 잘 생성하는 모델이라도 도구 호출을 올바르게 생성한다는 보장은 없습니다. 도구 스키마 이해, 인수 생성, 도구 결과를 읽은 후 작업을 이어가는 능력, 긴 맥락 유지가 필요합니다. 서버와 모델의 API 지원, 채팅 템플릿, 도구 파서가 함께 맞아야 합니다. 하네스의 파일 편집·셸 도구가 모델에 익숙한 형식인지도 확인합니다.
Ollama의 하네스별 안내는 64K 이상의 컨텍스트를 안내합니다.
이는 모든 모델의 공통 최소 사양이 아니라 해당 연결 안내의 기준입니다.
모델의 최대 길이와 가용 메모리 안에서 입력, 도구 정의, 대화 이력과 출력에 필요한 공간을 확보합니다.
컨텍스트를 늘리면 KV 캐시 메모리와 처리 비용도 증가합니다.
Ollama 컨텍스트 문서는 서버 설정과 ollama ps를 이용한 실제 컨텍스트 확인을 설명합니다.
4.1Ollama 서버 준비¶
다음은 도구 호출을 지원하는 모델을 내려받아 64K 컨텍스트를 가진 별도 이름으로 구성하는 예시입니다. 이미 실행 중인 서버가 있다면 별도 서버를 중복 실행하지 않고 기존 서버의 설정을 확인합니다.
OLLAMA_CONTEXT_LENGTH=65536 ollama serveOllama 서버 프로세스의 컨텍스트 설정 예시
다른 터미널에서 같은 서버를 대상으로 모델을 준비합니다.
ollama pull qwen3-coder도구 호출 모델의 준비
FROM qwen3-coder
PARAMETER num_ctx 65536Modelfile
ollama create coding-64k -f Modelfile
ollama list하네스용 모델 이름 생성
coding-64k는 이 예시에서 생성한 모델 이름이며, 이후 하네스 설정과 정확히 일치시킵니다.
모델 다운로드 크기와 메모리를 먼저 확인하고 장비에 맞는 도구 호출 모델을 선택합니다.
자세한 모델 생성 절차는 ollama create (Program 24)를 참고합니다.
4.2vLLM 서버 준비¶
아래 예시는 vLLM의 Claude Code 통합 문서와 도구 호출 문서의 GPT OSS 모델·파서 구성을 사용합니다. 선택한 체크포인트와 컨텍스트에 필요한 GPU 메모리를 확보해야 합니다.
vllm serve openai/gpt-oss-120b \
--served-model-name coding-model \
--host 127.0.0.1 --port 8000 \
--max-model-len 65536 \
--enable-auto-tool-choice \
--tool-call-parser openaivLLM 도구 호출 서버 예시
coding-model은 API에서 사용하는 별칭입니다. 모델 저장소 식별자와 클라이언트 모델 이름을 구분합니다.
다른 모델로 바꾸면 해당 모델의 채팅 템플릿, --tool-call-parser, 필요한 경우 --reasoning-parser도 공식 문서에 맞춰 변경합니다.
openai 파서를 모든 모델에 공통 적용하지 않습니다.
자동 도구 선택 옵션만으로 도구 호출을 학습하지 않은 모델에 해당 능력이 생기지는 않습니다.
5Claude Code CLI¶
5.1Ollama 연결¶
5.1.1간편 실행¶
Ollama 공식 안내는 프로젝트 디렉터리에서 다음 명령으로 모델을 선택하고 Claude Code를 실행합니다.
ollama launch claudeOllama의 Claude Code 간편 실행
앞에서 준비한 로컬 모델을 명시하려면 ollama launch claude --model coding-64k를 사용합니다.
환경 변수를 직접 나열하는 대신 실행 도우미가 연결을 구성합니다.
스크립트용 --yes는 --model과 함께 사용하며 선택 화면을 건너뛰고 필요하면 모델을 내려받습니다.
-- 뒤 인수는 Claude Code에 전달됩니다. 이 옵션은 Claude Code의 도구 실행 권한을 자동 승인하는 옵션과 다릅니다.
5.1.2수동 설정¶
공식 수동 설정에 따라 인증 토큰과 서버 주소, 모델 이름을 지정합니다.
로컬 Ollama는 토큰 값을 검증하지 않으며 ollama는 클라이언트가 요구하는 자리표시자입니다.
ANTHROPIC_BASE_URL=http://127.0.0.1:11434 \
ANTHROPIC_AUTH_TOKEN=ollama \
ANTHROPIC_API_KEY="" \
claude --model coding-64kOllama 모델을 사용하는 Claude Code 실행
Ollama의 Anthropic Messages 호환은 공식 발표에 따르면 v0.14.0부터 제공됩니다.
모든 Anthropic 기능을 그대로 구현하는 것은 아니므로 세부 요청 필드는 호환 범위를 확인합니다.
기존 Claude 설정의 주소나 인증 값이 적용되면 연결 대상이 달라질 수 있습니다. 실행 후 /status로 확인합니다.
5.2vLLM 연결¶
vLLM 공식 안내는 Messages API를 구현한 vLLM 서버로 직접 연결합니다. 별도 변환 프록시를 필수 구성으로 두지 않습니다.
ANTHROPIC_BASE_URL=http://127.0.0.1:8000 \
ANTHROPIC_API_KEY=dummy \
ANTHROPIC_AUTH_TOKEN=dummy \
ANTHROPIC_DEFAULT_OPUS_MODEL=coding-model \
ANTHROPIC_DEFAULT_SONNET_MODEL=coding-model \
ANTHROPIC_DEFAULT_HAIKU_MODEL=coding-model \
claude --model coding-modelvLLM 모델을 사용하는 Claude Code 실행
기본 모델 계층도 같은 별칭으로 맞춰 보조 요청이 존재하지 않는 Claude 모델 이름으로 전송되는 것을 방지합니다.
인증을 켜지 않은 서버에서 dummy는 자리표시자이며, 인증을 구성했다면 실제 키로 교체합니다.
vLLM 문서는 Claude Code의 모델 이름에 /가 포함되는 제약을 경고하므로 --served-model-name에 슬래시 없는 별칭을 사용합니다.
Claude Code의 요청별 시스템 프롬프트 해시 때문에 접두 캐시 효율이 낮아지는 문제는 vLLM 문서에서 0.17.1보다 높은 버전에 자동 대응이 있다고 설명합니다.
이전 버전은 ~/.claude/settings.json의 기존 env 객체에 "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"을 추가하는 우회법을 안내합니다.
이는 연결 지원 최소 버전과는 다른 성능 제약입니다. Messages API의 최초 지원 버전은 해당 통합 문서에 명시되어 있지 않으므로 설치 버전의 API 지원을 따로 확인합니다.
6Codex CLI¶
6.1Ollama 연결¶
6.1.1간편 실행¶
Ollama 공식 안내에 따라 Codex CLI를 먼저 설치하고 프로젝트 디렉터리에서 실행합니다.
ollama launch codexOllama의 Codex 간편 실행
실행 도우미는 모델 카탈로그를 갱신하고 해당 세션에 전용 Codex 프로필을 사용합니다.
Codex 안의 /model로 설치된 도구 호출 모델을 전환할 수 있습니다.
모델을 목록에 추가하려면 실행 전에 ollama pull <model>로 준비합니다.
ollama launch codex --config는 실행 없이 구성을 생성하며, ollama launch codex --restore는 실행 도우미의 프로필과 생성된 모델 카탈로그를 제거합니다.
아래 수동 프로필과 자동 생성 프로필을 구분하여 관리합니다.
6.1.2수동 설정¶
Ollama 공식 안내의 --oss 방식으로 로컬 모델을 선택할 수 있습니다.
codex --oss -m coding-64kOllama 모델을 사용하는 Codex 실행
로컬 공급자가 여러 개이면 Ollama를 선택합니다.
주소를 명시하거나 원격 서버를 사용하려면 다음과 같이 ~/.codex/config.toml의 기존 설정에 프로필과 공급자 항목을 병합합니다.
같은 TOML 테이블을 중복 선언하지 않습니다.
[profiles.local-ollama]
model = "coding-64k"
model_provider = "local-ollama"
[model_providers.local-ollama]
name = "Local Ollama"
base_url = "http://127.0.0.1:11434/v1"
wire_api = "responses"Codex의 Ollama 프로필 예시
codex --profile local-ollama주소를 명시한 Ollama 프로필 실행
이 프로필은 Codex 사용자 정의 공급자 설정을 적용한 수동 구성입니다.
ollama launch codex가 자동으로 생성하는 프로필·모델 카탈로그와 구분합니다.
Ollama의 Responses API는 v0.13.3에 추가되었으며, previous_response_id와 conversation을 사용하는 상태 유지 요청은 지원하지 않는다고 명시합니다.
최신 Codex 설정에서 wire_api는 responses만 지원하므로 과거의 chat 설정으로 대체하지 않습니다.
6.2vLLM 연결¶
vLLM 공식 안내에 따라 Responses API 공급자를 등록합니다.
[profiles.local-vllm]
model = "coding-model"
model_provider = "local-vllm"
[model_providers.local-vllm]
name = "Local vLLM"
base_url = "http://127.0.0.1:8000/v1"
env_key = "VLLM_API_KEY"
wire_api = "responses"Codex의 vLLM 프로필 예시
VLLM_API_KEY=dummy codex --profile local-vllmvLLM 모델을 사용하는 Codex 실행
인증이 없는 서버에서는 자리표시자를 사용하고, 인증을 켰다면 서버와 같은 키를 지정합니다. Chat Completions만 제공하는 vLLM 버전에는 이 설정으로 연결할 수 없습니다. 통합 문서는 Responses 지원 버전 사용을 요구하지만 정확한 최초 지원 번호는 제시하지 않습니다. 설치한 버전의 Responses 및 도구 호출 지원을 확인하고, 최신 문서의 예시가 오래된 서버에도 적용된다고 가정하지 않습니다.
7OpenCode¶
7.1Ollama 연결¶
7.1.1간편 실행¶
Ollama 공식 안내는 다음 명령으로 모델을 선택하고 OpenCode를 실행합니다.
ollama launch opencodeOllama의 OpenCode 간편 실행
선택한 모델의 인라인 구성을 전달하며 전역 ~/.config/opencode/opencode.json을 덮어쓰지 않습니다.
기존 OpenCode 설정도 적용되지만 opencode.json에만 정의한 모델은 실행 도우미의 모델 선택 목록에 나타나지 않습니다.
ollama launch opencode --config는 대화형 세션을 시작하지 않고 구성만 수행합니다.
구성 변경을 전혀 하지 않는 조회 명령으로 해석하지 않습니다.
7.1.2수동 설정¶
공식 공급자 설정에 따라 작업 프로젝트의 opencode.json에 다음 내용을 병합합니다.
전역 설정 위치와 우선순위는 구성 문서를 참고합니다.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"coding-64k": {
"name": "Coding 64K",
"limit": { "context": 65536, "output": 8192 }
}
}
}
}
}OpenCode의 Ollama 공급자 예시
opencode --model ollama/coding-64kOllama 공급자와 모델 선택
provider/model 형식으로 공급자 ID와 서버 모델 ID를 선택합니다.
모델의 limit는 하네스가 맥락과 출력을 관리하는 메타데이터입니다. 서버의 실제 num_ctx를 늘리는 설정이 아닙니다.
앞의 Ollama 서버 설정과 일치시키고 출력 공간도 모델 한도 안에서 잡습니다.
7.2vLLM 연결¶
사용자 정의 공급자의 Chat Completions 방식을 vLLM에 적용합니다.
다음 vllm 항목을 기존 provider 객체에 추가하면 Ollama와 함께 등록할 수 있습니다.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"vllm": {
"npm": "@ai-sdk/openai-compatible",
"name": "vLLM",
"options": {
"baseURL": "http://127.0.0.1:8000/v1",
"apiKey": "{env:VLLM_API_KEY}"
},
"models": {
"coding-model": {
"name": "Coding model",
"limit": { "context": 65536, "output": 8192 }
}
}
}
}
}OpenCode의 vLLM 공급자 예시
VLLM_API_KEY=dummy opencode --model vllm/coding-modelvLLM 공급자와 모델 선택
인증을 켰다면 실제 키를 환경 변수로 전달합니다.
OpenCode의 /connect에서 Other를 선택하여 공급자 ID vllm과 키를 저장하는 방식도 있습니다.
자격 증명 저장만으로 서버 주소와 모델이 등록되지는 않으므로 공급자 구성이 함께 필요합니다.
이 예시의 @ai-sdk/openai-compatible은 /v1/chat/completions용입니다.
OpenCode 문서는 Responses가 필요한 공급자에는 @ai-sdk/openai를 사용하도록 구분합니다.
8원격 서버와 SSH 터널¶
하네스별 launch 문서는 임의의 원격 Ollama 주소가 모든 하네스에 자동 전달되는 공통 절차를 명시하지 않습니다.
원격 연결에서는 아래 터널을 사용하거나 각 하네스의 수동 설정에 서버 주소를 명시합니다.
Ollama CLI가 원격 서버에 연결된다는 사실만으로 하네스의 추론 주소도 같다고 가정하지 않습니다.
원격 서버의 API에 직접 접근할 때는 클라이언트의 기본 주소에서 127.0.0.1을 서버 주소로 바꿉니다.
Ollama의 기본 바인딩은 루프백이므로 외부 접근이 필요하면 서버의 OLLAMA_HOST를 설정해야 합니다.
vLLM도 --host와 컨테이너 포트 게시 설정을 확인합니다.
인증 없는 모델 API를 공용 네트워크에 노출하지 않고 방화벽, 인증과 TLS 또는 SSH 터널을 사용합니다.
관련 서버 설정은 Ollama FAQ와 vLLM 보안 문서를 참고합니다.
ssh -N -o ExitOnForwardFailure=yes \
-L 127.0.0.1:11434:127.0.0.1:11434 \
-L 127.0.0.1:8000:127.0.0.1:8000 user@inference-host클라이언트에서 여는 로컬 포트 전달 예시
user@inference-host는 실제 SSH 계정과 호스트로 바꿉니다.
위 터널은 두 API가 SSH 서버의 루프백에서 접근 가능하다고 가정합니다.
서버가 컨테이너 안에 있으면 SSH 호스트의 루프백까지 포트가 게시되어 있어야 합니다.
터널을 연 상태에서는 앞의 여섯 연결 설정을 그대로 사용할 수 있습니다.
로컬 포트가 사용 중이면 예를 들어 18000:127.0.0.1:8000으로 바꾸고 하네스의 주소도 127.0.0.1:18000으로 맞춥니다.
하네스가 컨테이너 안에서 실행되면 그 컨테이너의 127.0.0.1은 Mac이나 SSH 호스트의 루프백과 다릅니다.
터널을 하네스와 같은 네트워크 환경에서 열거나 접근 가능한 호스트 주소를 사용합니다.
이때 하네스가 보내는 파일 내용과 도구 결과는 추론 서버로 전송되지만, 명령 실행 위치는 여전히 하네스 환경입니다.
9연결 확인과 오류 구분¶
각 하네스를 작업 디렉터리에서 실행한 뒤, 먼저 다음과 같이 읽기 중심 작업을 요청합니다.
현재 디렉터리의 README를 읽고 프로젝트 목적을 설명하세요. 파일은 수정하지 마세요.
연결 확인에서는 텍스트 답변뿐 아니라 파일 읽기 도구의 요청과 결과가 다음 응답에 반영되는지도 확인합니다. 모델이 도구 호출 모양의 텍스트만 출력하는 것은 정상 도구 실행과 다릅니다. 이후 임시 저장소에서 파일 편집과 제한된 명령 실행을 별도로 확인합니다. 하네스의 기본 권한 확인을 유지하고, 연결 문제를 해결하기 위해 권한 검사를 우회하지 않습니다.
| 증상 | 확인 대상 |
|---|---|
| 연결 거부 | 서버 실행 상태, 포트, 컨테이너 네트워크, SSH 터널 |
| 404 또는 API 형식 오류 | Messages·Responses·Chat Completions 구분, /v1 중복, 서버 버전 |
| 모델 없음 | Ollama의 생성 이름, vLLM의 --served-model-name, 하네스의 모델 ID |
| 도구 실행 없이 텍스트만 출력 | 모델의 도구 학습 여부, 채팅 템플릿, 파서, 스트리밍 호환성 |
| 긴 작업의 맥락 초과 | 실제 서버 컨텍스트, 하네스의 모델 한도, 출력 공간과 대화 누적량 |
| 의도하지 않은 서버 연결 | 전역·프로젝트 설정의 우선순위, 환경 변수, 자동 구성 프로필 |
CLI와 서버의 버전, 모델 식별자, 컨텍스트와 파서 설정을 함께 기록하면 재현에 도움이 됩니다. 일반 채팅이 성공해도 도구 호출, 이미지 입력, 사고 과정, 내장 웹 검색 등 모든 기능의 호환성을 보장하지는 않습니다.