安装 kie-chat-agents

KIE(api.kie.ai)的 chat 模型按各家厂商自己的 wire 协议对外提供。agent 的协议和模型的协议一致时,不需要适配层;不一致时,中间要放一个本地翻译代理,见下方「协议不一致时」一节。

一个 agent 一节,每节自成一体:怎么列出该 agent 能跑的模型、它要什么配置、它会怎么失败。目前覆盖了 Codex CLI、Claude Code 和 Grok Build;其他 agent 后续作为并列的章节加进来。协议不一致那一节是共用的,新 agent 不必再写一张配对表。

WARNING

⚠️ 使用 Agent 功能请选择最新版模型

Agent 功能请使用各系列的最新版模型。部分较早的模型目前仅支持对话调用，接入 Agent 可能会出现请求报错或结果异常，这类模型在 Market 的模型页上标有「仅支持对话调用」。具体可用的模型以各 Agent 的模型列表为准。

安装

npx skills add https://kie.ai

装好之后,可以直接对 Agent 说,例如“把 Codex 配置成使用 KIE”,skill 会按对应 Agent 页面的步骤完成配置。也可以照下面各页手动配置。

先决条件

一个 https://kie.ai/api-key 上创建的 KIE API key,导出为 KIE_API_KEY,以及装好你要配置的那个 agent。

列模型的片段需要 PATH 上有 curl 和 jq。多数系统不预装 jq:brew install jq、apt install jq 或 winget install jqlang.jq。

PowerShell 的 curl 是 Invoke-WebRequest 的别名,不接受这些参数。要像下面的 Windows 片段那样写 curl.exe。cmd.exe 下片段必须重写,不能直接粘贴。

三个 Agent 一览

以下内容归纳自各 Agent 页面,细节以对应页面为准。

Agent	协议	列模型	配置写在哪	base URL	凭据
Claude Code	Anthropic Messages	`GET https://api.kie.ai/anthropic/v1/models`	环境变量,或 `~/.claude/settings.json` 的 `env`	`ANTHROPIC_BASE_URL=https://api.kie.ai/anthropic`	`ANTHROPIC_AUTH_TOKEN` 放原始 key
Codex CLI	OpenAI Responses	`GET https://api.kie.ai/openai/v1/models`	`~/.codex/config.toml` 的 `[model_providers.kie]`	`https://api.kie.ai/openai/v1`	`env_key = "KIE_API_KEY"`
Grok Build	Responses(`api_backend = "responses"`)	`GET https://api.kie.ai/xai/v1/models`	`~/.grok/config.toml` 的 `[model.kie]`	`https://api.kie.ai/xai/v1`	`env_key = "KIE_API_KEY"`

三个 Agent 共同的规则:

模型名从 listing 里取,不要凭记忆写。 每次都重新跑 listing,模型集合会变。
用 Authorization: Bearer 认证。 名字就叫 apikey 的请求头会被 401 拒掉。
base URL 不要写完整请求 URL。 Agent 会自己往后拼 /v1/messages 或 /responses。
配置写进用户级文件,不要写进项目级文件。 项目级文件要么被忽略,要么会被提交进仓库。

协议不一致时

本 skill 里每个 agent 说一种 wire 协议,KIE 的每份 listing 也按一种协议提供。两者一致时,按该 agent 那一节配置,流量打到 api.kie.ai。不一致时,需要一个本地翻译代理。

什么时候需要代理

读该 agent 那一节:它说什么协议、会往后面拼哪一段。
读模型的 listing:KIE 按什么协议提供。
协议相同:不需要代理。协议不同:告诉用户需要本地翻译代理,并且 动手写之前先问。用户可能已经有代理,也可能这次并不想写。未经询问不要生成代理代码。
用户已有代理,或明确要求写一个之后,agent 的 base URL 指到代理,不指到 api.kie.ai。
列模型走 模型那一侧 的 listing,不走 agent 原生 listing。agent 的模型配置填那份列表里的 id——它内置的默认名和别名只对原生协议成立。

代理要暴露什么

模型 listing	KIE 请求	协议
`GET /openai/v1/models`	`POST /openai/v1/responses`	Responses
`GET /anthropic/v1/models`	`POST /anthropic/v1/messages`	Messages
`GET /xai/v1/models`	`POST /xai/v1/responses`	Responses

代理听的是 agent 会拼出来的那条路径,转到 该 listing 对应的 KIE 请求。两个方向都要翻译,包括 agent 实际会发的流式和 tool 调用。打到 KIE 的鉴权是 Authorization: Bearer $KIE_API_KEY。

以后新 agent 的 listing 不在这张表里时,加一行即可。这一节的规则不用改。

写代理时

只有用户明确要求时才写。映射要诚实,不要发明平台行为。

两种协议的形状从真实 agent 请求和官方协议里学,不要凭记忆填字段。 抓 agent 实际发出的请求(claude --debug、Codex 日志、GROK_LOG_FILE)和 KIE 在模型路径上要的形状。凭训练数据拼出来的字段表通常是残的。
model id 原样转发。 不要写死默认模型名,也不要把 sonnet / opus / claude-* 改写成 GPT slug,反过来也不要。
若代理要接 GET /models,返回的是 agent 期望的列表形状,数据来自模型那一侧的 KIE listing。 把另一边的文档原样转过去形状是错的。listing 失败就是错误,不要编一条假模型。
工具调用必须能走完一轮。 id / call_id / tool_use_id 在请求和下一轮的 tool result 里保持一致。不要丢掉 tools。KIE 若拒绝 tools,把那个错误传回去。
流式必须按 agent 结束一轮的方式收尾。 发出该 agent 会消费的事件序列,包括终态事件。KIE 中途报错或断流时,agent 必须看到失败,而不是 HTTP 200 加一轮空的 completed。
不要为了绕过协议限制而塞进新的 user/assistant 内容。 有的 Messages 模型拒绝以 assistant 收尾的对话。编一条后续 user 能让请求合法,但会改掉这一轮的语义——Codex 会因此不停续写。要么无损改形状,要么把上游错误原样返回。

把 agent 指到代理

监听地址是代理自己绑的。agent 的 base URL 仍按它那一节的规则写——Claude Code 会给 ANTHROPIC_BASE_URL 拼 /v1/messages,Codex 会给 base_url 拼 /responses,Grok Build 在 api_backend = "responses" 时也会给 base_url 拼 /responses——所以值里不要带上这段后缀。

把规则用到 Claude Code 跑 Responses 模型:

export ANTHROPIC_BASE_URL=http://127.0.0.1:<port>
export ANTHROPIC_AUTH_TOKEN=$KIE_API_KEY
export ANTHROPIC_MODEL=…

ANTHROPIC_MODEL 是 GET /openai/v1/models 里的 id,不是 Claude Code 的 sonnet / opus 别名。

把规则用到 Codex CLI 跑 Messages 模型:

model = "…"
model_provider = "kie"

[model_providers.kie]
name = "KIE"
base_url = "http://127.0.0.1:<port>/v1"
env_key = "KIE_API_KEY"
wire_api = "responses"

model 是 GET /anthropic/v1/models 里的 id。base_url 仍然不要带 /responses。

不要一边让 agent 的 base URL 还指着 api.kie.ai,一边发另一份 listing 里的 id;也不要把 agent 直接指到模型那一侧的 KIE 前缀而不经翻译。

本 skill 不提供什么

本 skill 不包含、不生成、也不点名任何翻译代理。它只声明监听路径、KIE 路径、该读哪份 listing,以及 agent 里哪个配置项填代理地址。只有用户明确要求时才写代理代码。