Kimi Hermes Agent

상위 문서: ← Kimi Integrations 출처: Kimi API Platform 공식 문서 — Use Kimi K3 in Hermes Agent 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

Hermes Agent는 Nous Research의 오픈소스 AI 에이전트로, 영구 메모리·도구 사용을 제공하며 CLI·Telegram·Discord·Slack·WhatsApp 인터페이스를 지원합니다.

이 가이드는 Hermes Agent를 Global Kimi Open Platform에 연결하고, 1M 토큰 컨텍스트 윈도우와 네이티브 시각 이해가 가능한 kimi-k3를 설정합니다. Hermes의 API Base URL은 https://api.moonshot.ai/v1이며, 실제 Chat Completions 엔드포인트는 https://api.moonshot.ai/v1/chat/completions입니다.

이 가이드의 스크린샷은 Hermes Agent v0.18.2 기준입니다. 이후 릴리스에서 메뉴 라벨이 바뀔 수 있지만, Global Kimi Open Platform API Key, kimi-k3, https://api.moonshot.ai/v1 사용은 동일합니다.

사전 준비

호출에 가용 잔액 필요. 등급별 한도는 Rate Limits 참고. IP 화이트리스트 사용 시 Organization Best Practices 참고.

1단계: Global Kimi 프로바이더 + K3 선택

hermes model

프로바이더 목록에서 Kimi / Moonshot 선택 → Hermes Agent v0.18.2 기준 첫 번째 서브메뉴(Kimi / Kimi Coding Plan) 선택. 이 항목이 Global Moonshot API의 내장 진입점입니다. KIMI_API_KEY 입력 시 Hermes가 입력 중 가려줍니다.

Global Open Platform Key를 사용하는 경우 Hermes가 다음을 출력해야 합니다:

Using Moonshot endpoint → https://api.moonshot.ai/v1

모델 목록에 kimi-k3가 없으면 Enter custom model name 선택 후 kimi-k3 입력 (moonshot/ 접두사 금지).

API Key를 config.yaml, 커맨드 인자, 스크린샷, Git 저장소에 절대 넣지 마세요. 이 가이드는 Global Kimi Open Platform Key 사용을 전제로 합니다.

2단계: K3 전체 설정 추가

hermes config edit

기존 custom_providers 목록에 kimi-k3-global 항목을 추가하고, 나머지 필드는 대응되는 최상위 섹션에 병합합니다. 최상위 섹션이 이미 있으면 중복 생성 대신 기존 필드를 갱신하세요. 무관한 설정과 기존 커스텀 프로바이더는 보존합니다.

custom_providers:
  - name: kimi-k3-global
    base_url: https://api.moonshot.ai/v1
    key_env: KIMI_API_KEY
    api_mode: chat_completions
    model: kimi-k3
    extra_body:
      reasoning_effort: max
    models:
      kimi-k3:
        context_length: 1048576
        supports_vision: true

model:
  provider: custom:kimi-k3-global
  default: kimi-k3
  context_length: 1048576
  supports_vision: true

agent:
  reasoning_effort: max

auxiliary:
  vision:
    provider: main
    model: kimi-k3
    extra_body:
      reasoning_effort: max

이 설정은 Kimi K3가 현재 지원하는 최대 reasoning effort, 1M 토큰 컨텍스트 윈도우, 네이티브 이미지 이해를 명시적으로 활성화합니다. 비디오 분석도 같은 K3 메인 프로바이더로 라우팅합니다. reasoning_effort는 최상위 Chat Completions 요청 필드로 low·high·max를 지원하며 max가 기본값입니다.

base_url은 반드시 https://api.moonshot.ai/v1만 지정하세요. Hermes가 OpenAI 호환 클라이언트를 사용해 /chat/completions를 자동으로 붙입니다. 완전한 요청 엔드포인트를 base_url에 넣지 마세요.

3단계: 공식 비디오 도구 활성화

hermes tools enable video

이제 Hermes가 공식 video_analyze 도구를 호출할 수 있습니다. 로컬 비디오는 완전한 파일을 읽어 data:video/...;base64,...로 인코딩한 뒤 kimi-k3에 단일 video_url content 블록으로 전송합니다. 이 경로는 FFmpeg로 로컬 프레임을 먼저 추출하지 않습니다.

Hermes Agent v0.18.2는 MP4, WebM, MOV, AVI, MKV, MPEG 등 일반 포맷을 지원하며 약 50MB Base64 비디오 페이로드 한도가 있습니다. 이 한도는 Hermes 클라이언트의 비디오 도구 하드캡으로 인한 것이며 Kimi API의 한도가 아닙니다. 더 큰 비디오는 먼저 트림·압축하세요.

활성화 명령은 한 번만 실행합니다. 이후 비디오 분석에는 추가 설정·/video 명령이 필요 없습니다. Hermes 채팅에서 절대 비디오 경로를 제공하며 video_analyze를 명시적으로 호출하도록 요청:

Call video_analyze on /absolute/path/to/demo.mp4, summarize the video, and list three details that can be confirmed from the visuals.

HTTP/HTTPS 비디오 URL을 직접 제공할 수도 있습니다.

4단계: Hermes Agent 시작

hermes

상태 표시줄에 kimi-k3와 1M 컨텍스트 윈도우가 표시되어야 합니다.

이미지 사용

절대 경로로 로컬 이미지 첨부:

/image /absolute/path/to/example.png

또는 클립보드에 이미지를 복사한 뒤 /paste 실행 → 질문 입력. Hermes가 kimi-k3로 네이티브 시각 입력을 전송합니다.

트러블슈팅

모델 목록에 `kimi-k3`가 없음

hermes model을 다시 실행해 Kimi / Moonshot > Kimi / Kimi Coding Plan → Enter custom model name → kimi-k3 입력.

잘못된 엔드포인트

이 가이드는 Hermes가 Using Moonshot endpoint → https://api.moonshot.ai/v1을 출력해야 합니다. Kimi Open Platform에서 발급한 Key를 사용하고 hermes model을 다시 실행.

API Key 거절

Global Kimi Open Platform Key를 hermes model로 다시 입력. 조직이 IP 화이트리스트를 사용하면 호출자의 공인 IPv4가 허용되는지 확인.

429 오류

동시 요청 수 줄이기, 재시도 전 대기, rate-limit 등급 확인.

비디오 도구 미호출

hermes tools enable video를 실행했는지, video_analyze를 명시적으로 요청했는지, 절대 로컬 경로를 사용했는지 확인. 인코딩 페이로드는 약 50MB 이하여야 합니다.

자세한 내용은 Troubleshooting 참고.

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 Hermes Agent 통합 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거