Use Kimi K3 in Hermes Agent

Hermes Agent is an open-source AI agent from Nous Research. It provides persistent memory, tool use, and interfaces including the CLI, Telegram, Discord, Slack, and WhatsApp. This guide connects Hermes Agent to the Global Kimi Open Platform and configures kimi-k3 with its 1M-token context window and native visual understanding. The API Base URL in Hermes is https://api.moonshot.ai/v1; the actual Chat Completions endpoint is https://api.moonshot.ai/v1/chat/completions.

The screenshots in this guide use Hermes Agent v0.18.2. Menu labels may change in later releases, but continue to use a Global Kimi Open Platform API key, kimi-k3, and https://api.moonshot.ai/v1.

Prerequisites

Complete these prerequisites before you start. Follow the linked official guides for installation and account setup.

Install Hermes Agent

Install or update Hermes Agent with the official instructions.

Create an API key

Create a Global Kimi Open Platform API key and keep it private.

Check account settings

Confirm that the account has available balance, then check limits, budgets, and organization settings.

You need available balance to call the API. See Rate Limits for the current tiers. If your organization uses an IP whitelist, follow Organization Best Practices and add the public egress IPv4 address of the computer or gateway that calls the API.

Step 1: Select the Global Kimi provider and K3

Run the model configuration wizard:

hermes model

Select Kimi / Moonshot in the provider list.

In Hermes Agent v0.18.2, select the first submenu item, currently labeled Kimi / Kimi Coding Plan. This is also the built-in entry for the Global Moonshot API. When prompted for KIMI_API_KEY, paste the key created at platform.kimi.ai; Hermes masks it while you type.

For a Global Open Platform key, Hermes should print:

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

If kimi-k3 is not in the model list, select Enter custom model name, then enter kimi-k3. Do not add a moonshot/ prefix.

Do not put the API key in config.yaml, command arguments, screenshots, or a Git repository. This guide uses a Global Kimi Open Platform key; do not substitute a key from another Kimi service or region.

Step 2: Add the complete K3 configuration

Run:

hermes config edit

Append the kimi-k3-global item below to the existing custom_providers list, then merge the remaining fields into their corresponding top-level sections. If a top-level section already exists, update its fields instead of creating a duplicate. Preserve unrelated settings and existing custom providers.

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

This configuration explicitly enables Kimi K3’s currently supported maximum reasoning effort, 1M-token context window, and native image understanding. It also routes video analysis through the same K3 main provider. reasoning_effort is a top-level Chat Completions request field that supports low, high, and max with max as the default; the examples use max. See the Model Parameter Reference.

Set base_url to https://api.moonshot.ai/v1 only. Hermes uses an OpenAI-compatible client and appends /chat/completions automatically. Do not put the complete request endpoint in base_url.

Step 3: Enable and use the official video tool

Run:

hermes tools enable video

Hermes can now call its official video_analyze tool. For a local video, the tool reads the complete file, encodes it as data:video/...;base64,..., and sends it to kimi-k3 in one video_url content block. This path does not extract frames locally with FFmpeg first. Hermes Agent v0.18.2 supports common formats including MP4, WebM, MOV, AVI, MKV, and MPEG, with an approximately 50 MB Base64 video payload limit. This limit comes from the Hermes client’s video tool hard cap, not from the Kimi API. Trim or compress larger videos before use. Run the enable command only once. For later video analysis, no additional setup or /video command is required. In a Hermes chat, provide an absolute video path and explicitly ask it to call 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.

You can also provide a directly accessible HTTP or HTTPS video URL.

Step 4: Start Hermes Agent and use K3

Start a new session so the provider, context, and tool settings are loaded:

hermes

The status bar should show kimi-k3 and a 1M context window.

Use an image

Attach a local image with an absolute path:

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

You can also copy an image to the clipboard, run /paste, and then enter your question. Hermes sends the image to kimi-k3 as native visual input.

Troubleshooting

`kimi-k3` is missing from the model list

Run hermes model again, select Kimi / Moonshot > Kimi / Kimi Coding Plan, then choose Enter custom model name and enter kimi-k3.

Hermes resolves the wrong endpoint

For this guide, Hermes must print Using Moonshot endpoint → https://api.moonshot.ai/v1. Use an API key created at https://platform.kimi.ai/console/api-keys, then run hermes model again.

The API key is rejected

Re-enter the Global Kimi Open Platform key with hermes model. If your organization uses an IP whitelist, confirm that the caller’s public egress IPv4 address is allowed.

You receive a 429 error

Reduce concurrent requests, wait before retrying, and check the account balance and current rate-limit tier.

The video tool is not called

Confirm that you ran hermes tools enable video, explicitly ask Hermes to call video_analyze, and use an absolute local path. The encoded payload must remain below approximately 50 MB. For more Kimi API guidance, see Troubleshooting.

Get Started

Model Capabilities

Tooling workflows

Core workflows

Integrations

Debugging and operations

Prerequisites

Install Hermes Agent

Create an API key

Check account settings

Step 1: Select the Global Kimi provider and K3

Step 2: Add the complete K3 configuration

Step 3: Enable and use the official video tool

Step 4: Start Hermes Agent and use K3

Use an image

Troubleshooting

`kimi-k3` is missing from the model list

Hermes resolves the wrong endpoint

The API key is rejected

You receive a 429 error

The video tool is not called

​Prerequisites

Install Hermes Agent

Create an API key

Check account settings

​Step 1: Select the Global Kimi provider and K3

​Step 2: Add the complete K3 configuration

​Step 3: Enable and use the official video tool

​Step 4: Start Hermes Agent and use K3

​Use an image

​Troubleshooting

​kimi-k3 is missing from the model list

​Hermes resolves the wrong endpoint

​The API key is rejected

​You receive a 429 error

​The video tool is not called

Prerequisites

Step 1: Select the Global Kimi provider and K3

Step 2: Add the complete K3 configuration

Step 3: Enable and use the official video tool

Step 4: Start Hermes Agent and use K3

Use an image

Troubleshooting

`kimi-k3` is missing from the model list

Hermes resolves the wrong endpoint

The API key is rejected

You receive a 429 error

The video tool is not called