在 Hermes Agent 里用 Kimi 模型：配置字段与常见问题

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

Hermes Agent 接 Kimi，官方文档专门拎出来强调的有三件事：选的是不是「中国区」那一条 Provider、Base URL 只写到 /v1、以及那段 YAML 要合并进现有配置而不是另起一份。 Kimi 官方文档给的路径是四步：hermes model 选中国区 Provider 并粘贴 Key，hermes config edit 把一整块自定义 Provider 配置写进去，hermes tools enable video 启用官方视频工具，然后开新会话让配置生效。Hermes Agent 是 Nous Research 开源的 AI Agent，官方介绍它支持持久化记忆、工具调用，以及 CLI、Telegram、Discord、Slack 和 WhatsApp 等多种交互方式。文档中的配置说明基于 Hermes Agent v0.18.2，官方特意提示后续版本菜单文字可能变化，但要接的东西不变：中国区 Kimi 开放平台 API Key、模型名 kimi-k3、Base URL 写到 https://api.moonshot.cn/v1 为止。

动手之前，先把账户这一侧确认掉

官方把准备工作单列了一节，放在所有操作步骤之前，里面有两条前提值得先看。

第一条是余额与模型可用性。文档明确写着 Kimi K3 需要充值后使用，并且新用户认证赠送的代金券不能用于 Kimi K3。这意味着「账户里有代金券」和「K3 可用」在官方口径里是两回事，所以动手配置之前先把可用余额这一格确认掉，别拿代金券当余额。官方文档里没有说明只有代金券时会在哪一步、以什么形式失败，所以也别指望从返回文字上认出这个前提没满足。同一段里官方还写了另外两件事：调用限额随用户等级变化，具体规则以充值与限速页面为准；如果组织启用了 IP 白名单，要先按组织最佳实践把当前网络的出口 IPv4 地址加进去。

第二条是 IP 白名单。这是开放平台的组织级安全配置，官方说明里写得很清楚：配置并保存后，仅白名单内的 IP 可以访问当前组织下的 API，不在白名单内的 IP 发起 API 请求时将无法访问当前组织资源；白名单为空时不限制调用来源。还有两个细节值得单独记：保存时系统会用当前填写的列表整体覆盖原有配置，也就是说漏填一条等于删掉一条；以及它只支持公网 IPv4 地址或规范的 IPv4 CIDR 网段，暂不支持 IPv6。如果你的 Hermes 跑在云主机、NAT 网关或公司网络后面，要填的是实际访问 Kimi API 时用的那个出口公网 IP，而不是本机看到的地址。

安装 Hermes 本身和创建 API Key 这两步，官方让你按各自的官方指引走，文档里不展开。

第一步：hermes model，选中国区那一条

跑模型配置向导，一级菜单选 Kimi / Moonshot，二级菜单选 Kimi / Moonshot (China)，然后在掩码输入框里粘贴中国区 Kimi API Key。这里有个很实用的细节：Hermes 会把 Key 保存到本机的私密环境配置中，对应的变量名是 KIMI_CN_API_KEY。记住这个变量名，因为下一步 YAML 里要靠它去引用，而不是把 Key 明文写进配置文件。

接下来向导会让你确认 Base URL，官方要求保留默认值直接回车：

Base URL [https://api.moonshot.cn/v1]:

选默认模型时，如果列表里没有 kimi-k3，官方给的做法是选 Enter custom model name，然后手输 kimi-k3。这里有一条明确的禁止项：不要添加 moonshot/ 之类的前缀。官方没有说明加了前缀之后会返回什么，所以这条按禁止项照做就行——要手输的模型名就是 kimi-k3 本身，前后都不要再补厂商命名空间。

官方还专门提醒了 Key 的保管方式：不要把 API Key 写入 config.yaml、命令参数、截图或 Git 仓库；并且中国区、国际站和 Kimi Coding Plan 使用不同的 API Key，请勿混用。文档里另外单列了一条常见问题「API Key 无效或请求被拒绝」，给的动作是确认使用的是中国区 Kimi 开放平台创建的 API Key 并重新输入一遍；但官方并没有把「混用」和这条问题绑成因果，也没有说明混用时的返回内容长什么样。落到操作上更稳的做法是给每把 Key 记清来源站点，出问题时直接回控制台核对，而不是靠返回文字反推。关于 Key 的通用保管思路，可以参考API Key 安全管理。

第二步：那段 YAML 每个字段在管什么

运行 hermes config edit，把官方给的 kimi-k3-cn 条目追加到现有 custom_providers 列表里，其余字段合并到对应的顶层区域。官方对合并方式说得很细：如果已有同名顶层区域，改里面的字段，不要重复创建；如果已有其他自定义 Provider，保留它们。

custom_providers:
  - name: kimi-k3-cn
    base_url: https://api.moonshot.cn/v1
    key_env: KIMI_CN_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-cn
  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

逐块看：custom_providers 里的 key_env 指向上一步存下的环境变量名，所以配置文件里始终没有明文 Key；api_mode: chat_completions 声明走的是 Chat Completions 这条协议；models.kimi-k3 下面的 context_length 与 supports_vision 是在告诉客户端这个模型的上下文长度和是否具备视觉能力。顶层 model 区域里 provider 写的是 custom:kimi-k3-cn，和上面 custom_providers 条目的 name 对应，default 同样是 kimi-k3。官方这一页只给出了这段 YAML 本身，没有解释 custom: 这个前缀的拼写规则，所以照抄的时候把这两处保持一致就好，别顺手给 Provider 改个自己顺眼的名字。

最后那块 auxiliary.vision 值得单独说：它的 provider 写的是 main，意思是视觉这一路复用主 Provider，而不是另起一套连接。官方对这组配置的整体说法是，它明确启用 Kimi K3 当前支持的最高推理强度、1M token 上下文和原生图片理解，同时让视频分析复用同一个 K3 主 Provider。上下文长度以官方文档为准。

base_url 只写到 /v1

官方把这条单独拎出来强调了一遍：base_url 只填 https://api.moonshot.cn/v1，Hermes 使用 OpenAI 兼容客户端时会自动追加 /chat/completions，不要把完整请求地址写进 base_url。实际的 Chat Completions 请求地址是 https://api.moonshot.cn/v1/chat/completions，但那是客户端拼接后的结果，不是你要填进配置的值。官方没有描述填成完整地址之后会得到什么样的报错，所以这条不用靠认报错来排查——配置写完回头看一眼这一行，结尾是不是停在 /v1，比事后猜省事得多。

reasoning_effort 是请求顶层字段

配置里出现了三处 reasoning_effort，它不是 Hermes 自造的参数。官方文档说明这是 Chat Completions 请求的顶层字段，用来调节 Kimi K3 的推理深度、延迟与 token 消耗，取值为 low / high / max 三档，默认取最高那一档（默认值可能随版本调整，以官方文档当前版本为准）。这三处在配置里分别落在 custom_providers[].extra_body、顶层 agent 和 auxiliary.vision.extra_body 下面；官方这一页没有逐个解释它们各自的作用域，只给出了整组配置的整体效果说明，所以照抄就整组照抄，别只改其中一处。至于 extra_body 这个名字，Kimi 文档在别的页面提到过它的用途：OpenAI SDK 没有原生对应字段的 Kimi 专有参数，需要通过 SDK 的 extra_body 传递。

另外，如果你是从 K2.x 迁过来的，官方给的迁移动作是：移除 K2.x 的 thinking 配置，并按需使用顶层 reasoning_effort。注意官方用的词是「移除」，不是在旧字段旁边再叠一个新字段。同类的换平台核对清单可以参考换厂商迁移清单。

第三步：视频工具是客户端能力，不是 API 能力

hermes tools enable video 只需要执行一次，启用后 Hermes 就可以调用官方的 video_analyze 工具。这一步的机制值得认真读一遍，因为它决定了你能拿它干什么。

官方描述的链路是：对于本地视频，该工具会读取完整文件，把它编码为 data:video/...;base64,...，再以一个 video_url 内容块发送给 kimi-k3；这条链路不会先在本地用 FFmpeg 抽帧。也就是说，整段视频是以一个内容块的形式进入请求体的，没有本地预处理帮你降体积。

由此就有了那条载荷上限：Base64 视频载荷有一个上限，官方明说这个限制来自 Hermes 客户端视频工具的硬编码上限，并非 Kimi API 的限制；这个上限由客户端硬编码，具体数值以官方文档为准。较大的视频，官方给的办法是先裁剪或压缩。支持的容器格式，官方在 v0.18.2 下列出的是 MP4、WebM、MOV、AVI、MKV 和 MPEG 这几种常见格式（以官方文档为准）。

用法上还有一个反直觉的地方：启用之后不需要再用 /video 命令，而是在对话里给出视频的绝对路径，并明确要求调用 video_analyze。官方给的示例就是这种写法——让模型「调用 video_analyze 分析某个绝对路径的文件，概括内容并列出能从画面中确认的细节」。也可以直接给一个可访问的 HTTP 或 HTTPS 视频 URL。

第四步：开新会话，看状态栏

配置改完之后直接跑 hermes 开一个新会话，官方的说法是让新的 Provider、上下文和工具配置全部生效。官方给这一步的判据只有一条，也很直观：状态栏应该显示 kimi-k3 和 1M 上下文。状态栏对不上就别急着回去改 YAML，先按这一步重新开一个会话再看一眼。

图片这一路不用额外开工具：用 /image 加图片的绝对路径，或者把图片复制到剪贴板后用 /paste 再提问。官方说明图片会作为原生视觉内容发送给 kimi-k3，而不是先转成文字描述。

官方给的五类问题怎么判

文档结尾的常见问题这一节，实际是一份对照表，值得按症状记：

• 模型列表里没有 kimi-k3：重新跑 hermes model，走 Kimi / Moonshot → Kimi / Moonshot (China)，选 Enter custom model name 手输模型名。
• 连到了错误的 Endpoint：中国区向导里的默认值应该就是 https://api.moonshot.cn/v1。官方让你确认用的是在中国区控制台 API Keys 页面创建的 Key，然后重跑 hermes model。
• API Key 无效或请求被拒绝：先确认 Key 来自中国区开放平台，重新输一遍；如果组织启用了 IP 白名单，还要确认当前出口 IPv4 地址在白名单里。
• 429：官方在这一页给的动作是降低并发、稍后重试，同时检查账户余额和当前用户等级的调用限额。值得补一句的是，Kimi 的错误码文档把 429 拆成了几种不同的 error type：engine_overloaded_error 表示服务节点负载较高，官方明确说这类错误由服务端容量导致，充值或提升 Tier 不能直接消除，给的动作是按照 Retry-After 提示等待、降低并发并使用指数退避重试；rate_limit_reached_error 才是真正撞上了组织级的并发、RPM、TPM 或 TPD 限制，官方按撞到的是哪一种分别给了降低并发、按响应提示等待后重试、降低调用频率或升级 tier、次日恢复或升级套餐这几种动作；exceeded_current_quota_error 指向欠费、停用或 token 额度不足，这一类靠等和重试解决不了，要回控制台处理账单与额度。所以拿到 429 别只看状态码，先看 error type 和响应里的 Retry-After，再决定是等一等还是回控制台。这套通用处理思路见 429 该怎么处理。
• 视频工具没被调用：确认执行过 hermes tools enable video，并且在请求里明确写出要调用 video_analyze；本地文件必须用绝对路径，编码后的载荷不能超过客户端上限。

最后：照抄配置时要盯住的三处

一是 Key 走错站点。中国区、国际站、Kimi Coding Plan 三套 Key 官方明写了不要混用，动手之前先确认手里这把是从中国区控制台的 API Keys 页面建出来的。二是 base_url 写全。写到 /v1 就停手，剩下的路径由客户端拼。三是配置合并。官方在这一步反复强调的是「把条目追加到现有 custom_providers 列表」「已有同名顶层区域就改里面的字段，不要重复创建」「已有其他自定义 Provider 请保留」，所以编辑 config.yaml 的动作应该是往现有结构里填字段，而不是把整段贴到文件末尾了事。

如果你还在别的客户端里接 Kimi，配置逻辑是同一套，只是落点不同，可以对照在 Claude Code 里配 Kimi 一起看。