OpenHands + JoinGonka Gateway: 나만의 엔드포인트 에이전트

현재 프로젝트에는 여러 인터페이스가 있으며, 실행 중인 인터페이스에 따라 모델 설정 위치가 달라집니다. 설정값 자체는 어디서든 동일하지만 설정 경로가 다릅니다.

Agent Canvas를 사용하려면 Node.js와 uv가 필요합니다(에이전트의 로컬 서버가 이를 기반으로 작동함. 자세한 내용은 설치 가이드 참조). 가이드에서는 Node.js 22.12 이상을 권장하지만, 1.17 버전 이후 패키지는 Node.js 24 이상을 요구하므로 호환성 경고를 피하려면 24를 설치하십시오. 컨테이너 버전도 있으며, ghcr.io/openhands/agent-canvas 이미지는 http://localhost:8000/canvas에서 인터페이스를 제공하고 마운트된 디렉터리만 접근 가능합니다.

JoinGonka 키. gate.joingonka.ai/register에서 가입 및 이메일 인증 후, "API Keys" 섹션에서 jg- 접두사가 포함된 키를 생성하십시오. 하나의 키와 잔액으로 네트워크의 모든 모델을 사용할 수 있습니다. 설치 프로그램의 도구 목록에 OpenHands용 @joingonka/setup은 없으나, 이는 누락된 것이 아닙니다. 설정값이 외부에서 수정 가능한 텍스트 파일이 아니라 인터페이스 및 백엔드의 보안 저장소에 위치하기 때문입니다.

1단계. Agent Canvas를 실행하고 Settings > LLM으로 이동합니다. 첫 실행 마법사가 고유한 OpenHands 프로바이더를 제안하는데, 이 단계는 건너뛰어도 나중에 쉽게 설정으로 돌아올 수 있습니다.

2단계. Add LLM Profile을 클릭하고 Advanced 탭으로 이동합니다. Basic 탭에서는 내장 목록에 있는 프로바이더와 모델만 선택할 수 있기 때문입니다.

3단계. 다음 세 필드를 입력합니다:

4단계. 프로파일을 저장합니다. 저장하기 전에 Canvas는 백엔드 요청을 통해 구성을 확인합니다. 키가 거부되거나 모델을 사용할 수 없는 경우 프로파일이 저장되지 않고 오류 메시지가 표시됩니다.

5단계. 새로운 대화를 시작하고 짧은 메시지를 보냅니다. 이미 열려 있는 대화는 시작할 때 사용한 모델로 계속 작동합니다.

openai/를 사용하는 이유. LiteLLM은 모델 접두사를 통해 프로바이더를 결정합니다. openai/ 접두사는 "OpenAI 모델"을 의미하는 것이 아니라 "OpenAI Chat Completions 프로토콜을 사용하여 서버와 통신함"을 의미합니다. 첫 번째 세그먼트만 제거되므로 게이트웨이에는 실제 식별자인 deepseek-ai/DeepSeek-V4-Flash-0731이 전달됩니다. OpenHands 문서에서도 openai/qwen/qwen3.6-35b-a3b 예제를 통해 동일한 방식을 보여줍니다. 접두사가 없으면 LiteLLM은 LLM Provider NOT provided 메시지와 함께 작동을 거부합니다.

/v1으로만 끝나야 하는 이유. LiteLLM은 공식 OpenAI 클라이언트를 통해 서버에 접근하며, 이 클라이언트가 자동으로 /chat/completions를 덧붙입니다. 따라서 주소는 반드시 /v1으로 끝나야 합니다. 접미사가 없으면 요청이 API에 도달하지 못하고, 불필요한 내용이 있으면 존재하지 않는 경로로 전송됩니다. Canvas의 또 다른 요구 사항은 주소가 브라우저뿐만 아니라 백엔드에서도 접근 가능해야 한다는 점입니다. 게이트웨이는 공개 HTTPS 주소이므로 Docker 컨테이너에서도 호스트와 동일하게 보입니다. host.docker.internal과 같은 설정은 본인 기기에서 모델을 실행할 때만 필요합니다.

세 가지 모델 각각에 프로파일 생성. 네트워크의 각 모델에 대해 프로파일을 생성하고 deepseek, glm, minimax와 같이 짧은 이름을 지정하세요(문서에는 프로파일 10개 제한이 명시되어 있습니다). 대화 중 컨텍스트를 잃지 않고 입력 필드의 프로파일 선택 버튼이나 /model glm 명령어를 사용하여 전환할 수 있습니다. 인자 없이 /model을 입력하면 목록이 표시됩니다. 모든 프로파일에 키를 넣지 않으려면 Provider Connections 블록에 한 번만 저장하세요. 이는 로컬 백엔드에서 사용할 수 있습니다.

Docker의 이전 인터페이스. 필드는 동일합니다: Settings → LLM 탭 → Advanced 활성화 → Custom Model, Base URL, API Key 입력 → Save Changes.

CLI는 uv를 통해 한 줄 명령으로 설치되며, 첫 실행 시 모델 설정 마법사가 자동으로 열립니다. 나중에 설정으로 돌아가려면 Ctrl+P → Settings 입니다:

uv tool install openhands --python 3.12
openhands

스크립트에서는 환경 변수가 더 편리합니다. 중요한 점: 기본적으로 CLI는 환경 변수를 무시하며, --override-with-envs 플래그를 붙였을 때만 적용합니다. 한 번의 실행에만 적용되고 아무것도 저장되지 않습니다:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

같은 세트는 인터페이스 없이도 동작합니다 — CI와 배치 작업용입니다:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

헤드리스 모드에서 에이전트는 항상 자동 승인으로 동작하므로, 모든 것을 허용할 수 있는 곳 — 별도 디렉터리나 컨테이너 — 에서 실행하세요. --json 플래그는 출력을 JSONL 이벤트 스트림으로 변환하여 파이프라인에서 파싱하기 좋습니다. 바로 이 방식으로 우리는 2026년 9월 21일 CLI 1.16.0에서 이 조합을 검증했습니다: CLI 상단에 Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731이 출력되고, 이어서 에이전트가 파일을 읽고 핵심을 답합니다.

CLI의 저장된 설정은 ~/.openhands/agent_settings.json에 있습니다. 모델을 바꾸려면 llm 블록의 세 필드 — model, api_key, base_url — 을 수정하면 됩니다. 파일을 처음부터 만들지는 마세요: 첫 실행 마법사가 다른 에이전트 설정도 거기에 기록하기 때문입니다. 대화 기록 압축도 그중 하나이며, 이것이 없으면 긴 대화는 컨텍스트 윈도우에 부딪힙니다.

에이전트를 자체 코드에 내장한다면, OpenHands SDK도 같은 세 가지 값을 받습니다:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

네트워크 모델의 가격이 동일하기 때문에 선택은 모델의 동작에 따라 결정됩니다. 자율형 에이전트에게 중요한 숫자는 두 가지입니다. 컨텍스트 윈도우: 각 단계마다 기록을 새로 전송하므로 윈도우가 길수록 에이전트가 손실 없이 더 오래 작업할 수 있습니다. 응답 상한(Output Limit): 에이전트가 큰 파일을 전체적으로 작성하는 단계는 하나의 응답 내에 들어와야 합니다. 표는 OpenHands CLI 1.16.0 및 SDK 1.21.0을 사용하여 동일한 작업(파일 읽기 및 오류 찾기)을 실행한 결과입니다.

장시간 작업을 위한 작업 체계는 OpenHands 문서의 조언을 따르는 것이 좋습니다. 한 모델로 계획하고 다른 모델로 실행하는 방식입니다. glm 프로필에서 대화를 시작하여 파일 수정 없이 계획을 요청한 뒤, /model deepseek를 입력하여 실행 명령을 내리십시오. 전환 시에도 기록, 파일, 작업 상태가 유지됩니다. minimax 프로필을 세 번째로 유지하면 다른 모델의 용량이 피크 시간대에 부족할 때 유용하게 전환할 수 있으며, Settings > Application에서 대화 제목 생성을 맡길 수도 있습니다.

기록 압축. 수십만 토큰의 윈도우라 하더라도 장시간 작업에서는 한계가 있습니다. OpenHands에서는 이를 위해 컨덴서(Condenser) 기능을 제공합니다. 기록된 이전 이벤트를 짧은 요약으로 줄여줌으로써 대화가 길어져도 지연 시간과 토큰 소모를 줄여줍니다. Agent Canvas에서는 Settings > Condenser 섹션에서 설정할 수 있으며, 이번 CLI 테스트에서는 80개 이벤트 임계값으로 자동으로 활성화되었습니다.

모델 제한. OpenHands는 컨텍스트 윈도우와 응답 상한을 LiteLLM 참조 데이터에서 가져오는데, 여기에는 Gonka 네트워크 식별자가 포함되어 있지 않아(LiteLLM 1.81 기준 확인) 에이전트가 해당 모델에 대한 자체 값을 가지지 않습니다. 하지만 작업에는 지장이 없습니다. 게이트웨이가 위 표를 기준으로 응답 상한을 직접 적용하기 때문입니다. 제한을 명시적으로 설정하려면 SDK의 max_input_tokens 및 max_output_tokens 필드를 사용하고, Canvas에서는 All 탭을 통해 프로필 전체 필드에 접근할 수 있습니다. 기본 모델에 대한 자세한 내용은 DeepSeek V4 Flash 개요를 참조하세요.

요청이 실제로 게이트웨이를 통과하고 있는지 확인하는 방법은 두 가지입니다. OpenHands 측에서는, 새로운 대화를 시작하여 "README를 읽고 한 문장으로 요약해줘"와 같은 간단한 작업을 시킵니다. 에이전트가 도구를 호출하고 답변을 하면 성공입니다. 게이트웨이 측에서는 관리자 페이지의 "사용량(Usage)" 섹션을 확인합니다. 요청이 "모델별(By Model)" 분류에 나타나고, "키별(By Keys)" 블록에서 마지막 요청 시간이 업데이트되면 정상입니다. 아무것도 없다면 다른 프로필에서 대화가 진행 중일 수 있으므로, 어떤 것이 활성으로 표시되어 있는지 확인하십시오.

OpenHands 문서에 따르면 429 오류 발생 시 재시도 횟수와 대기 시간은 LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT, LLM_RETRY_MAX_WAIT 변수로 설정할 수 있습니다. 문서와 SDK의 기본값이 다를 수 있으므로 실제 설정을 확인하십시오. CLI 1.16.0 대화 상태에서 8초~64초 대기 시간을 포함한 5회의 재시도를 확인했습니다.

JoinGonka Gateway를 통한 토큰 가격은 입력 100만 토큰당 $0.0069, 출력 100만 토큰당 $0.021이며, 네트워크의 모든 모델에 동일하게 적용됩니다. 이 가격은 이 페이지에서 실시간 소스를 통해 자동으로 반영됩니다.

오른쪽 열의 추정치는 2026년 9월 가격 기준입니다. 에이전트 경제 체계에 대한 상세 내용은 AI 에이전트를 위한 가장 저렴한 API 관련 기사에서 확인할 수 있습니다.

지출 한도. OpenHands는 지출 한도 설정을 권장하지만, 본 게이트웨이에는 결제 모델 자체에 한도가 내장되어 있습니다. 잔액은 선불 방식이며 에이전트가 계정 잔액보다 더 많이 사용할 수 없습니다. 잔액 및 일일 사용량은 관리자 페이지에서 확인할 수 있습니다. CI 및 백그라운드 자동화를 위해 별도의 키를 생성하여 메인 계정과 소비를 분리하십시오. 일일 한도가 있는 하위 키에 대한 내용은 Management Keys 관련 기사를 참조하십시오.

신뢰 경계. npm을 통해 실행되는 Agent Canvas는 사용자의 권한으로 작동하며 파일 시스템 전체를 볼 수 있습니다. 신뢰할 수 없는 코드의 경우 Docker 버전을 사용하십시오. 에이전트는 마운트된 디렉토리만 볼 수 있습니다. 이는 OpenHands 자체의 특성이며 모델 제공자와 무관합니다.

대화 기록 유지. OpenHands는 대화 기록을 자체 ~/.openhands에 저장하고 매 단계마다 모델에 전송합니다. 게이트웨이는 기록을 저장하지 않으며, 답변 후 프롬프트와 코드가 게이트웨이에 남지 않습니다.

이미지(인터페이스 스크린샷, 도식 등)가 포함된 작업의 경우는 vision 모델용 프로필을 별도로 만드십시오. Gonka 네트워크의 모델은 텍스트 전용입니다. 코드, 명령, 파일에 대해서는 제약 사항이 아닙니다.