OpenHands

Settings → LLM → Advanced에서 세 필드 — Custom Model, Base URL, API Key — 를 입력하며, 모델 ID에는 openai/ 접두사를 붙이고 기본 URL에는 /v1을 유지합니다

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. Settings → LLM을 열고 Advanced 토글을 켜세요. 세 필드는 Custom Model, Base URL, API Key 순서로 표시됩니다.
3. 접두사가 포함된 모델 ID를 입력하세요. openai/claude-sonnet-5이지 claude-sonnet-5가 아닙니다. Kunavo가 제공하는 ID는 GET /v1/models가 반환하는 값이며, OpenHands 자체 문서에서도 사용자 지정 ID를 여기서 가져오라고 안내합니다.
4. https://api.kunavo.com/v1를 Base URL에 붙여 넣고 키를 API Key에 입력한 다음 Save Changes를 클릭하세요. OpenHands 문서에 따르면 로컬 프로필을 저장할 때 먼저 백엔드에 구성 유효성을 확인하고, 실패하면 저장을 차단합니다. 따라서 여기서 발생하는 오류는 단순한 표시 문제가 아니라 실제 거부를 의미합니다.
5. 브라우저에서 연결할 수 있는지가 아니라 백엔드에서 연결할 수 있는지 확인하세요. 기본 URL은 Agent Server가 실행되는 컴퓨터에서 확인할 수 있어야 합니다. 문서에는 Agent Canvas가 Docker에서 실행된다면 127.0.0.1가 컨테이너라고 명시되어 있습니다. Kunavo처럼 공개 엔드포인트를 사용하는 경우는 간단하지만, 그 앞에 기업 프록시가 있으면 그렇지 않습니다.
6. 새 대화를 시작하고 파일을 읽고 수정하는 작업을 맡기세요. OpenHands는 저장된 LLM이 새 대화에 적용되며 기존 대화는 먼저 다시 시작해야 한다고 안내합니다. 또한 도구를 사용하는 실행을 통해 인사말만 주고받는 것보다 모델 조합을 더 정확하게 확인할 수 있습니다.

OpenHands의 Language Model (LLM) 설정 페이지에서 확인했습니다(2026년 9월 21일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 OpenHands에서 작동합니다.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

필드에 입력할 model id

모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.

문제를 진단하기 전에 알아둘 세 가지 경계

OpenHands는 단일 프로세스 CLI보다 구성 요소가 많으며, 그중 두 가지는 LLM 엔드포인트처럼 보이지만 실제로는 다릅니다. 아래 내용은 위 날짜를 기준으로 확인한 OpenHands 자체 문서를 바탕으로 합니다.

1. 샌드박스는 모델이 아닙니다. OpenHands는 에이전트 서버 샌드박스에서 작업을 실행하고 네트워크를 통해 모델을 호출합니다. 이 둘은 별도의 자격 증명을 사용하는 서로 다른 인터페이스입니다. 여기에 설정한 키는 모델 호출에 사용됩니다. 샌드박스가 접근할 수 있는 대상과는 무관하며, 샌드박스 네트워크 문제는 인증 오류로 나타나지 않습니다.
2. ACP 에이전트는 완전히 별도로 처리됩니다. Agent Canvas는 Claude Code, Codex 또는 Gemini CLI에 ACP 에이전트로 작업을 위임할 수 있으며, Configure a Model 페이지에서는 이들이 "자체 모델 접근을 관리한다"고 명시합니다. 따라서 LLM 프로필은 해당 하위 프로세스의 경로를 바꾸지 않습니다. 키에서 트래픽이 발생할 것으로 예상했는데 아무것도 보이지 않는다면 실제로 어떤 에이전트가 실행 중인지 확인하세요. OpenHands와 Claude Code 비교에서 자격 증명의 우선순위를 결정하는 규칙을 포함해 이 차이를 설명합니다.
3. 프로필과 프로필 10개 제한. 저장한 구성이 LLM 프로필이 되고, 가장 최근에 저장한 프로필은 새 대화에 활성화됩니다. 대화 중에도 컨텍스트를 잃지 않고 프로필을 전환할 수 있습니다. 이 기능을 통해 하나의 키로 저렴한 ID와 비싼 ID를 모두 사용할 수 있습니다. 문서에 따르면 계정당 프로필은 최대 10개입니다. 공급자 연결에는 여러 프로필에서 사용할 공급자, API 키, 선택적 기본 URL을 한 번 저장할 수 있습니다. 같은 페이지에는 이 패널이 로컬 agent-server 백엔드에서만 제공되고 OpenHands Cloud 백엔드에서는 숨겨진다고 나와 있습니다.