Tool Integrations2026年9月22日Flatkey Team

如何在 Claude Code 中使用任意模型：SKILL.md 设置

在 Claude Code 中安装 Flatkey 的 SKILL.md，发现实时模型 ID，运行安全的冒烟测试，并了解何时使用网关环境变量。

当 Claude Code 了解你的 AI 路由层是如何工作时，它会变得有用得多。SKILL.md 设置是一种清晰的方式，可以教它这套工作流：Flatkey 的路由器位于何处、如何发现实时模型 ID、如何调用受支持的模型和工具，以及在花费余额或接触生产系统之前应遵循哪些安全规则。

首先有一个重要的注意事项。Claude Code 自身的推理循环仍然运行在 Claude 上。Anthropic 的网关文档说明 Claude Code 可以连接到一个 LLM 网关，但它不支持通过网关将 Claude Code 本身路由到非 Claude 模型。请把本指南用于 How to Use Claude Code with Any Model: The SKILL.md Setup 的实用版本：保留 Claude Code 作为你的编码代理，然后给它一个 Flatkey skill，这样当任务需要时，它就可以从你的项目中发现并调用任何 Flatkey 支持的模型或计量工具。

Flatkey 的公开 SKILL.md 就是为此而构建的。它告诉代理使用 https://router.flatkey.ai、OpenAI 兼容的基础 URL https://router.flatkey.ai/v1、实时模型目录、工具市场、小额首次调用、请求 ID，以及在写入、发送、购买、删除、发布或权限更改之前的审批关卡。

如果你刚接触路由器本身，请将 Flatkey API 快速入门与本指南并排打开。如果你是在将其与更广泛的提供商迁移进行比较，OpenAI API 替代方案和统一 AI API 工作流指南会更详细地解释基础 URL 模式。

快速答案

当你希望 Claude Code 在你的仓库中操作 Flatkey 时，请使用此设置：

在 Flatkey Console 中创建一个 Flatkey API key。
将 Flatkey skill 安装到 Claude Code，路径为 ~/.claude/skills/flatkey/SKILL.md 或 .claude/skills/flatkey/SKILL.md。
将 FLATKEY_API_KEY 存储在你的 shell 或本地密钥管理器中，而不是提交到仓库的文件里。
让 Claude Code 使用 Flatkey skill，获取实时模型目录，并通过 https://router.flatkey.ai/v1 运行一个很小的冒烟调用。
检查 Flatkey Usage Logs 中的模型、token 数、延迟、状态和成本。

如果你希望 Claude Code 的 Claude 系列流量通过 Flatkey，请使用 Flatkey 的 Claude Code 指南，而不是 OpenAI 兼容的 /v1 基础 URL：

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

这条路径用于 Claude Code 网关路由。SKILL.md 路径则用于教 Claude Code 如何从项目中使用 Flatkey 模型和工具。

SKILL.md 会在 Claude Code 中改变什么

Claude Code skill 是一个包含 SKILL.md 文件的目录。Claude Code 在启动时加载 skill 元数据，然后仅在任务匹配或你直接调用该 skill 时才读取 skill 正文。这使得 skill 比 CLAUDE.md 更适合作为可重复流程的存放位置，例如“发现 Flatkey 模型，选择受支持的路由，运行一个小调用，并验证 Usage Logs”。

使用 Flatkey 时，该技能应使 Claude Code 持续执行以下五件事：

步骤	Claude Code 应该做什么	这为何重要
读取设置规则	在调用路由器之前加载 Flatkey 的 `SKILL.md`	避免猜测模型 ID、猜测工具输入以及泄露密钥
使用实时目录	在选择模型前调用 `/v1/models`	模型列表会变化，因此静态示例可能会过时
将密钥保留在本地	使用 `FLATKEY_API_KEY`，不要打印或提交它	防止凭据在聊天、日志和 git 中暴露
从小处开始	在执行昂贵任务前先运行一次小型 smoke 调用	确认身份验证、基础 URL、路由和响应格式
验证账本	在调用后检查 Usage Logs 或请求输出	为团队提供模型、延迟、token 和费用的证据

这就是 如何在 Claude Code 中使用任意模型：SKILL.md 设置 的实用核心。Claude Code 仍然是编排器。Flatkey 则成为它可以有意识操作的模型和工具层。

步骤 1：选择个人安装或项目安装

如果你希望在每个仓库中都可用，请全局安装该技能：

mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

如果你希望团队共享相同的 Flatkey 工作流，请将其安装在仓库内：

mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o .claude/skills/flatkey/SKILL.md

对于共享的项目技能，请在提交之前先审阅该文件：

sed -n '1,200p' .claude/skills/flatkey/SKILL.md

不要把安装命令变成自动运行的 shell 脚本。技能是一段说明内容。请像把其他任何开发流程加入仓库一样对待它：获取、审阅，然后只有在团队同意时才提交。

步骤 2：安全设置 Flatkey 密钥

使用环境变量：

export FLATKEY_API_KEY="sk-fk-your-key"

如果你需要让该变量持续生效，请把它放在 shell 配置文件、密钥管理器中，或一个被 git 忽略的本地环境文件里。不要把密钥放在 .claude/settings.json、CLAUDE.md、已提交的 SKILL.md，或你粘贴到共享线程中的提示词里。

Flatkey 技能本身的规则很简单：当已有 FLATKEY_API_KEY 已配置时就使用它，并且绝不要打印、记录、提交或发送该密钥到除 router.flatkey.ai 或已认证的 Flatkey Console 之外的任何地方。

步骤 3：确认 Claude Code 能看到该技能

从该技能可用的仓库或终端中启动 Claude Code：

claude

然后检查可用技能：

/skills

你应该会在技能列表中看到 flatkey。如果你是在 Claude Code 运行时安装该技能，而它没有出现，请重启 Claude Code。Claude Code 可以在会话期间检测到许多技能编辑，但在设置过程中，重启是消除歧义的最简单方法。

现在先请求一个无害的第一项任务：

Use the flatkey skill. Verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog from Flatkey, and summarize the first five text-capable model IDs you see. Do not run a generation yet.

这会在不消耗生成预算的情况下测试发现能力。

第 4 步：获取实时模型目录

Flatkey 技能会告诉 Claude Code 在选择模型之前先获取实时模型目录。直接命令是：

curl -fsS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

在真实工作流中，要求 Claude Code 只从返回的 ID 中进行选择：

Use the flatkey skill. Fetch the live model catalog, choose one low-cost text model returned by the catalog for a one-sentence smoke test, and explain why you chose it before running the request.

这避免了一个常见的代理错误：使用记忆中的模型名称，或来自旧文章的名称。目录是此刻你的密钥可以调用哪些模型的真实来源。

第 5 步：运行一个极小的 OpenAI 兼容冒烟调用

一旦目录返回，就通过 Flatkey 的 OpenAI 兼容 API 运行一个小请求：

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-a-model-id-from-the-live-catalog",
    "messages": [
      {
        "role": "user",
        "content": "Reply with one sentence: Flatkey smoke test passed."
      }
    ],
    "max_tokens": 40
  }'

把第一次调用保持得简单无聊。你要测试的是身份验证、模型 ID、基础 URL、响应结构和账本可见性。等基本路径正常后，再处理长上下文提示、工具调用、图像生成和批处理作业。

第 6 步：让 Claude Code 在任务中调用任意受支持的模型

冒烟测试通过后，你就可以要求 Claude Code 将工作路由到适合该任务的模型。

例如：

Use the flatkey skill. I need a second-model review of this function. Fetch the live catalog, select a coding-capable model returned by the catalog, run a small review request through Flatkey, and report the model ID, request result, and any request ID or usage fields returned. Do not print secrets.

或者：

Use the flatkey skill. Compare two Flatkey-supported text models on this prompt. Keep both calls under 200 output tokens. Show the outputs side by side and tell me which one I should use for this low-risk internal summarization task.

这就是适用于 Claude Code 的“任意模型”模式：Claude Code 负责协调任务、读取文件、应用仓库上下文，并在需要第二个模型或不同模型家族时，将 Flatkey 作为受控的外部模型路径使用。

对于生产环境中的模型选择，请将其与AI 模型目录指南配合使用，这样 Claude Code 就会在推荐路径之前审查端点类型、定价单位、可用性和验证状态。

第 7 步：仅在检查后使用 Flatkey 工具

Flatkey 的 SKILL.md 也涵盖了计量工具。重要规则是，Claude Code 应该在运行工具之前先检查它。它不应编造工具 ID、必填字段、价格、提供商名称或计费单位。

一个好的首个提示是：

使用 flatkey skill。在浏览器中打开 Flatkey 工具市场，检查我账户可用的与搜索相关的工具，并总结一个候选工具的必填字段和计费单位。先不要执行该工具。

然后，当你准备好时：

使用 flatkey skill。用一个较小的限制和一个幂等键运行已检查过的工具。在执行之前，请重复该工具的准确名称、必填字段、预期计费单位以及最大预算，供我批准。

这样可以让 Claude Code 保持有用，同时避免代理漂移到不可控的付费调用中。

第 8 步：在需要时通过 Flatkey 路由 Claude Code 的 Claude 流量

SKILL.md 的设置与将 Claude Code 本身通过网关路由并不相同。如果你的目标是让 Claude Code 的 Claude 系列请求通过 Flatkey 运行，请将 Claude Code 配置为 Anthropic 格式的网关客户端：

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

此路径不要带尾随的 /v1。Claude Code 和 Anthropic SDK 会自动附加所需路由。设置变量后，从同一个 shell 启动 Claude Code 并运行：

/status

查看 Anthropic base URL 和凭据来源。然后发送一个简短提示并检查 Flatkey Usage Logs。如果 base URL 没有出现，说明 Claude Code 没有接收到环境变量。

当你希望 Claude Code 的 Claude 用量记入 Flatkey 的余额和账本时，请使用此路径。当你希望 Claude Code 从你的仓库中调用 Flatkey 支持的模型和工具时，请使用 skill 路径。

关于相邻的路由决策，请参见Claude 与 GPT API 路由。如果你的用例是一个调用外部工具的代理，那么即使模型家族发生变化，Gemini API for AI agents 清单也很有用，因为这些控制项是相似的：精确的模型 ID、受限重试、工具验证和用量审查。

常见错误

错误 1：假设 SKILL.md 会改变 Claude Code 的“大脑”

不是。一个 skill 只是给 Claude Code 提供可复用的指令和流程。它不会把 Claude Code 自己的 agent 循环变成 GPT、Gemini、DeepSeek、Qwen 或其他模型。

错误 2：将 `/v1` 与 `ANTHROPIC_BASE_URL` 混用

Flatkey 的 OpenAI 兼容基础 URL 是：

https://router.flatkey.ai/v1

Claude Code 网关路由使用：

https://router.flatkey.ai

请将它们分开使用。

错误 3：在 Claude 设置中提交凭据

项目的 .claude/settings.json 通常会与仓库一起共享。不要把密钥放在那里。请使用 shell 导出、密钥库，或仅在你的仓库会忽略它且团队接受这种本地工作流时才使用 .claude/settings.local.json。

错误 4：让 agent 猜测模型 ID

务必先获取 /v1/models。如果某个模型 ID 不在与你的密钥对应的实时目录响应中，就不要使用它。

错误 5：在检查付费工具之前就运行它们

对于 Flatkey Tools，先检查必需字段、示例、计费单位和准确价格。然后使用幂等键，并在执行前请求批准。

可直接复制的设置清单

在一台开发者机器上使用此清单：

# 1. 为 Claude Code 安装 Flatkey skill
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

# 2. 审阅它
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md

# 3. 导出你的 Flatkey 密钥
export FLATKEY_API_KEY="sk-fk-your-key"

# 4. 启动 Claude Code
claude

然后提示：

Use the flatkey skill. Confirm the Flatkey skill is loaded, verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog, and run one tiny chat-completions smoke test through https://router.flatkey.ai/v1 using a model ID returned by the catalog.

调用完成后，打开 Flatkey Usage Logs，并确认该请求以预期的模型、状态、token 数、延迟和成本显示出来。

常见问题

Claude Code 可以通过 SKILL.md 使用任意模型吗？

Claude Code 本身仍然运行在 Claude 上。SKILL.md 设置让 Claude Code 能够从你的项目中发现并调用 Flatkey 支持的模型和工具，因此在合适的时候，任务可以通过 Flatkey 的 API 使用其他模型。

这和修改 `ANTHROPIC_BASE_URL` 是一回事吗？

不是。ANTHROPIC_BASE_URL=https://router.flatkey.ai 会把 Claude Code 的 Claude 系列流量通过网关路由。安装 https://flatkey.ai/SKILL.md 则是在任务期间教会 Claude Code 如何操作 Flatkey 的 API 和工具。

我应该全局安装 Flatkey skill，还是安装到仓库中？

在跨项目的个人使用场景中，请使用 ~/.claude/skills/flatkey/。当仓库需要承载共享的团队工作流时，请使用 .claude/skills/flatkey/。只提交经过审阅的 skill 文件，绝不要提交凭据。

为什么指南会先获取 `/v1/models`？

因为模型可用性会变化。实时的 Flatkey 目录比从记忆、聊天回答或旧文档中复制来的模型名称更安全。

设置完成后我应该验证什么？

请验证三件事：Claude Code 能看到该 skill，Flatkey 目录请求成功，以及 Usage Logs 显示了带有模型、状态、token、延迟和成本的 smoke 请求。

官方参考

Flatkey SKILL.md: https://flatkey.ai/SKILL.md
Flatkey 快速开始: https://docs.flatkey.ai/quickstart.md
Flatkey Claude Code 指南: https://docs.flatkey.ai/guides/claude-code.md
Flatkey OpenAI SDK 指南: https://docs.flatkey.ai/guides/openai-sdk.md
Anthropic Claude Code skills: https://code.claude.com/docs/en/skills
Anthropic Claude Code gateway 文档: https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
Anthropic gateway 连接指南: https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
Anthropic Agent Skills 概览: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview