让 Claude Code 与 Codex 直连 Kimi K3，再用上下文缓存省钱

这一课做完你会得到什么

Claude Code 和 Codex CLI 都改用 Kimi K3 作为后端模型，并各自通过一次验证；你还会用一个脚本亲眼看到上下文缓存命中，学会在 5 分钟和 1 小时两档 TTL 之间选。

第 1 步：先用 curl 验证 Anthropic 兼容端点

Claude Code 走的是 Anthropic Messages 格式，Kimi 对应的端点是 https://api.moonshot.cn/anthropic。先用一次最小请求确认 Key 可用：

curl https://api.moonshot.cn/anthropic/v1/messages \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model": "kimi-k3", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}'

返回正常的 JSON（"type": "message"）即说明端点和凭据都可用。我们用假 Key 实测得到的是 401：

{"error":{"message":"Invalid Authentication","type":"invalid_authentication_error"}}

第 2 步：安装 Claude Code

需要 Node.js 18+。官方文档给出的安装命令使用 npmmirror 镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
claude --version

claude --version 打印出版本号即安装成功。

如果你以前给 Claude Code 配置过别的第三方模型，先检查 ~/.bashrc、~/.zshrc 里有没有残留的 export ANTHROPIC_...，有就删掉；同时注意已有的 ANTHROPIC_API_KEY 会和下面的 ANTHROPIC_AUTH_TOKEN 冲突，也要删除。

第 3 步：在 settings.json 里把模型切到 Kimi

打开（没有就新建）~/.claude/settings.json，写入下面的 env，把 YOUR_MOONSHOT_API_KEY 换成你的 Key。官方示例让 HAIKU 档用 kimi-k2.7-code，其余档位都用 kimi-k3[1m]：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_MOONSHOT_API_KEY",
    "ANTHROPIC_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k2.7-code",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "kimi-k3[1m]",
    "CLAUDE_CODE_SUBAGENT_MODEL": "kimi-k3[1m]",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  }
}

如果文件里已经有别的配置（权限、主题等），只把 env 这一块合并进去。几个要点：

• settings.json 里的 env 会覆盖终端里 export 的同名变量；文件里是明文 Key，不要提交到 git。
• Claude Code 的主对话、后台摘要、子 Agent 会用不同档位的模型，少配一个变量，对应场景就会静默失败，所以四个 ANTHROPIC_DEFAULT_*_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL 都要配。
• 模型名里的 [1m] 是写法的一部分，表示使用 1M 上下文，要原样保留。
• kimi-k2.7-code 强制开启思考，必须在 Claude Code 里打开 Thinking（macOS 按 Option+T，Windows / Linux 按 Alt+T），否则会报 400 invalid thinking: only type=enabled is allowed for this model。

第 4 步：验证 Claude Code

改完 settings.json 要重启 Claude Code。进入任意项目目录：

cd ~/your-project
claude

在会话里输入：

/status

对照结果：Base URL 显示 https://api.moonshot.cn/anthropic，Model 显示 kimi-k3[1m]。再输入 /model 能看到你配置的模型；随便发一句「你好」能收到回复，就是端到端成功。

排错速查（来自官方常见问题）：401 先查 Key 是否替换、是否删掉了旧的 ANTHROPIC_API_KEY；提示 model not found 多半是 kimi-k3[1m] 拼错或多了空格引号；后台任务或子 Agent 报错，说明 HAIKU / FABLE / SUBAGENT 某个变量没配。

第 5 步：让 Codex CLI 直连 Kimi K3

Kimi 原生支持 Codex 使用的 Responses API，不需要本地代理。先按 OpenAI 官方文档 https://learn.chatgpt.com/docs/codex/cli 安装并至少启动一次 Codex CLI。

把 Key 放进 KIMI_API_KEY 环境变量（用 read -s 输入，Key 不会出现在命令历史里）：

read -s KIMI_API_KEY
export KIMI_API_KEY
test -n "$KIMI_API_KEY" && echo set || echo missing

最后一行打印 set 即可。然后编辑 ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\config.toml），已有的 model、model_provider 直接替换：

model = "kimi-k3"
model_provider = "kimi"
model_context_window = 1048576

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.cn/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"

wire_api = "responses" 是直连的关键；model_context_window 让 Codex 按 K3 的 1M 上下文计算。退出正在运行的 Codex，重新进入项目：

cd ~/your-project
codex

对照结果：界面显示当前模型为 kimi-k3；启动时出现 Model metadata for kimi-k3 not found 警告是官方说明的预期现象，不影响使用。发一句「你好」能回复，再发「检查这个仓库并总结它的结构。」能在读完文件后给出总结，说明模型调用和工具调用都正常。

Codex 侧的常见报错：404 /v1/responses 说明 base_url 没写成恰好 https://api.moonshot.cn/v1；401 说明 Key 无效或启动 Codex 的终端里没有 KIMI_API_KEY。

第 6 步：用脚本看到上下文缓存命中

编程 Agent 每一轮都会重复发送 system prompt、工具定义和代码库内容，这正是上下文缓存省钱的地方。Kimi 对重复前缀自动缓存，不用手动创建。K3 的相关价格（每 100 万 tokens）：

新建 cache_demo.py，用一段较长的固定资料当前缀，连问两次，观察 usage：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

knowledge = "你是一个产品文档问答助手。\n\n产品文档：\n" + "\n".join(
    f"第 {i} 条：本产品支持账号密码、短信验证码和企业 SSO 三种登录方式。" for i in range(1, 400)
)

for question in ["这个产品支持哪些认证方式？", "企业用户应该用哪种方式登录？"]:
    completion = client.chat.completions.create(
        model="kimi-k3",
        reasoning_effort="low",
        messages=[
            {"role": "system", "content": knowledge},
            {"role": "user", "content": question},
        ],
        extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
    )
    usage = completion.usage
    details = usage.prompt_tokens_details
    print(
        f"prompt={usage.prompt_tokens} "
        f"cached={getattr(details, 'cached_tokens', None)} "
        f"cache_write={getattr(details, 'cache_write_tokens', None)}"
    )

python3 cache_demo.py

对照结果的规律（具体数字随分词不同）：第一行 cached 为 0 或很小、cache_write 接近整段资料的 token 数；第二行 cached 接近资料的 token 数、cache_write 接近 0。三者（未缓存、缓存读取、缓存写入）之和等于 prompt_tokens。

要点：

• prompt_cache_options 是 Kimi 扩展参数，OpenAI SDK 里要放进 extra_body；mode 目前只支持 implicit，ttl 支持 5m（默认）和 1h。用 Anthropic 格式时改用请求顶层的 cache_control: {"type": "ephemeral", "ttl": "1h"}。
• 缓存按前缀匹配：把固定的 system prompt、工具定义、资料放在最前面，用户问题放最后；前缀里不要插时间戳、随机 ID。
• 不足一整块的部分写不进缓存，会按未命中计费，所以很短的前缀看不到效果。
• 流式请求要加 stream_options={"include_usage": True}，最后一个 chunk 才会带完整的缓存用量。
• TTL 在首次写入时锁定，过期前不能改；缓存按组织隔离，不能手动清除。

第 7 步：5 分钟还是 1 小时

官方给的算法：选 1h 比 5m 多付的只有写入费（¥40 对 ¥20，多 ¥20）；之后每命中一次，这部分输入从 ¥20 降到 ¥2，省 ¥18。所以在 1 小时内只要再命中 2 次，1h 就比 5m 净省 ¥16（以 100 万 tokens 前缀计）。

请求间隔通常 < 5 分钟（连续跑的 Agent）     → 用默认 5m
间隔可能 > 5 分钟但 1 小时内会复用（人工介入）→ 用 1h
相同前缀通常隔 1 小时以上才复用              → 不必专门配置

控制台 https://platform.kimi.com/console/cache 的 Caching 概览页可以看各模型的缓存命中率和写入摊销倍数。

自查清单

• curl 访问 /anthropic/v1/messages 返回正常 JSON
• Claude Code 的 /status 显示 Kimi 的 Base URL 和 kimi-k3[1m]
• Codex 显示当前模型 kimi-k3，能读仓库并总结结构
• cache_demo.py 第二次请求的 cached 明显大于 0
• 你能根据请求间隔决定用 5m 还是 1h