Jan Agent

`jan config set --base-url https://api.kunavo.com/v1` 한 줄로 Kunavo를 ~/.jan/config.toml에 기록하며, 추론 엔진을 제공하지 않는 Jan Agent 미리보기 CLI가 해당 키로 실행됩니다

# Jan Agent is a preview on a nightly channel — check your build first.
jan --version

jan config set \
  --provider kunavo \
  --api-key sk-kn-... \
  --base-url https://api.kunavo.com/v1 \
  --model claude-sonnet-5 \
  --model claude-haiku-4-5 \
  --api-type openai

jan config list   # configured providers as JSON, keys redacted

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. 설정하려는 대상이 jan --version인지 확인하세요. Jan Desktop에는 jan로 실행하는 CLI도 포함되어 있지만 명령 구성이 다릅니다. 나머지 명령을 입력하기 전에 jan config set --help 목록에 --base-url가 있는지 확인하세요.
3. 위의 jan config set 명령을 실행하세요. --provider은 고정 목록에서 선택하는 이름이 아니라 직접 정하는 ID입니다. 문서의 로컬 하드웨어 예시에서는 --provider local를 사용합니다. --model은 반복해서 사용할 수 있으며, 기존 목록에 추가하는 대신 목록 전체를 바꿉니다.
4. jan config list(키는 마스킹됨) 또는 파일 자체의 jan config path로 설정이 적용되었는지 확인한 다음, jan cli models list를 실행해 모든 제공자가 제공하는 모델을 확인하세요. 직접 입력한 모델 ID는 엔드포인트 목록에서 사라져도 유지됩니다. 반면 jan cli models refresh --provider kunavo는 엔드포인트 목록을 기준으로 삼습니다.
5. 프로젝트 디렉터리로 이동해 jan를 실행한 다음 /model로 모델을 선택하세요. 첫 실행에는 jan --plan를 권장합니다. 읽기 전용이므로 프로토콜이 맞지 않으면 디스크에 변경 사항을 쓰기 전에 확인할 수 있습니다.
6. 파일을 수정하는 작업을 지정하세요. Jan Agent는 에이전트이므로 첫 실행에서 도구 호출과 스트리밍을 확인해야 합니다. 일부만 호환되는 엔드포인트에서는 이 기능부터 문제가 생길 수 있지만, 인사말로는 어느 쪽도 확인할 수 없습니다.

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

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

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

# 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 기준이며 입력 / 출력 순서입니다.

Jan API 키라고 불리는 서로 다른 두 가지 항목

두 항목은 같은 파일에 저장되지만 의미는 정반대입니다. 따라서 다른 항목을 예상하는 경우 jan config list가 잘못된 것처럼 보일 수 있습니다.

Jan Desktop은 둘 다 발급하지 않습니다. 계정이 없으므로 발급할 것이 없습니다. 로컬 API 서버에는 직접 만든 키를 사용하며, 이는 또 다른 세 번째 의미이자 다른 호스트에 해당합니다.

Jan Desktop에서 전달되는 정보와 그 한계

Jan Agent는 공급자 설정을 네 가지 출처에서 읽으며, 각 출처는 위에 있는 출처보다 우선합니다. 두 번째 출처는 많은 사람을 놀라게 합니다.

1. ~/.jan/config.toml — 기본 파일이며, jan config set가 기록하는 유일한 파일입니다.
2. Jan Desktop의 settings.json — 상속 전용입니다. Agent에 설정하지 않은 공급자를 추가하지만, 이미 설정한 공급자를 덮어쓰지 않으며 이 파일에 다시 기록하지도 않습니다.
3. 프로젝트의 agent.toml에 있는 [provider] 블록 — 프로젝트별로 명시적으로 선택하므로 앞의 두 출처보다 우선합니다. 일반적으로 이 파일은 커밋되므로 api_key를 여기에 넣지 마세요.
4. 명령줄의 --provider / --api-key 또는 JAN_API_KEY / <PROVIDER>_API_KEY — 가장 명시적이면서 가장 일시적인 설정입니다.

잘못된 항목을 디버깅하기 전에 알아둘 점이 두 가지 있습니다. jan config list에는 공급자가 없다고 나오지만 jan cli models list에는 여러 개가 표시될 수 있습니다. 후자에는 상속된 Desktop 공급자가 포함되지만, 이들은 ~/.jan/config.toml에 저장되지 않습니다. 또한 상속된 공급자는 새로 고쳐지지 않습니다. 다시 쓸 항목이 여기에 없기 때문입니다. Kunavo의 모델 목록을 최신 상태로 유지하려면 자체 jan config set 항목으로 추가해야 하며, 위 블록이 바로 그런 항목을 만듭니다.

두 공급자가 같은 모델 ID를 제공하는 경우

Kunavo는 claude-sonnet-5 같은 ID를 제공하며, 공급자 항목을 벤더에 직접 연결해도 같은 ID를 제공할 수 있습니다. Jan Agent는 하나를 선택해야 하며, 문서에 명시된 순서는 다음과 같습니다. 먼저 공급자의 models 목록에서 정확히 일치하는 항목을 찾고, 다음으로 설정된 공급자를 지정하는 <provider>/<model> 접두사를 확인합니다. 같은 ID를 제공하는 항목이 여러 개라면 인증 정보가 있는 공급자가 키가 없는 공급자보다 우선합니다. 따라서 kunavo/claude-sonnet-5를 사용해 원하는 공급자를 지정할 수 있습니다. 이 한정자는 Jan에서만 사용되며, 공급자 접두사가 붙은 ID를 업스트림에서 거부하므로 요청을 보내기 전에 제거됩니다.

콘솔에서 같은 항목 설정하기

플래그를 직접 입력하고 싶지 않다면 /settings > providers에서 동일한 ~/.jan/config.toml 항목을 관리할 수 있습니다. a를 누르면 name, base url, api key 및 공백으로 구분한 models를 입력하는 양식이 열립니다. 이 양식에서만 가능한 작업이 두 가지 있습니다. 원격 엔드포인트에는 키가 평문으로 전송되지 않도록 기본 URL이 https://(로컬호스트 엔드포인트라면 http://)이어야 합니다. Kunavo는 https://이므로 문제가 되지 않습니다. 또한 항목을 수정할 때 API 키 필드에는 (unchanged)가 표시되며, 입력하지 않으면 저장된 키를 유지합니다. 필드를 비우면 키를 그대로 두는 대신 삭제합니다.