本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.5 · SDK 2.6.9。英文原文

免费层 API 快速入门

状态：生效范围：当前状态最近审阅：2026-08-28 负责人：ax-code 运行时

AX Code 不提供模型配额。一次“免费”运行使用的是外部模型提供商提供的配额或积分，其可用性、限制、数据条款和模型目录可以独立于 AX Code 变化。

最短的受支持路径：Groq

Groq 是默认的 AX Code 提供商，其当前的 AX Code 模型目录包含具备工具能力的模型，并且 Groq 为这些模型 ID 公布了免费方案限制。

在 Groq 控制台创建 Groq 账户和 API 密钥。
把密钥存入 AX Code：

ax-code providers login groq

确认你已安装的 AX Code 版本中可用的模型：

ax-code models groq

打开 ax-code，运行 /connect，并选择 Groq 和所列模型之一。对于无头冒烟测试，当前捆绑目录支持：

ax-code run --model groq/openai/gpt-oss-120b "Inspect this repository without editing it and summarize its purpose."

如果 ax-code models groq 没有打印出那个确切模型，请使用它所打印的模型 ID。已安装的目录对已安装的版本是权威的。

内置的免费层和免费积分选项

这些提供商位于 AX Code 的默认设置选择器中。“内置”表示 AX Code 提供协议适配器、模型元数据、凭据流程和提供商端点；并不表示每个模型或每次请求都免费。

AX Code 提供商	零成本路径	重要约束
`groq`	Groq 免费方案	速率限制按模型和账户计；请查看 Groq 的实时限制。
`google`	免费层 Gemini API 模型	只有在 Gemini API 价格中标记为免费的模型才符合。Google 声明免费层内容可能被用来改进其产品。
`unorouter`	以 `:free` 结尾的模型 ID	UnoRouter 是第三方网关。其免费模型限制有意设得很低，可用性可能波动。
`huggingface`	周期性的 Inference Providers 积分	免费账户目前会收到一小笔月度积分，可能变更；见 Hugging Face 价格。一次完整的代理任务就可能用尽它。
`zai`	PAYG API 上当前的 GLM-5.3 SKU	AX Code 的选择器从 GLM-5.3 开始。连接 `zai` 提供商，而不是 `zai-coding-plan`，并查看 Z.AI 价格以了解当前的零成本 SKU。
`openrouter`	`openrouter/free`，或模型专属的 `:free` 变体	提供商预设是内置的，但 AX Code 精选快照目前没有列出免费路由器。请按下方所示显式添加它。

对于 UnoRouter，用 ax-code providers login unorouter 连接，运行 ax-code models unorouter，并选择 ID 以 :free 结尾的模型。不要假定没有该后缀的付费孪生模型是免费的。UnoRouter 自己的目录注明，并非每个免费模型都支持工具调用；AX Code 在其捆绑目录中只呈现具备工具能力的条目。

对于 Google 或 Hugging Face，用匹配的提供商 ID 连接，然后使用 ax-code models google 或 ax-code models huggingface。选择模型之前请查看该提供商的实时价格页。

添加 OpenRouter 的免费模型路由器

OpenRouter 把 openrouter/free 记录为一个零成本路由器，它会选择与请求兼容的、可用的免费模型。因为该路由器不在 AX Code 当前的精选快照中，请向你项目根目录的 ax-code.json 添加一条保守的本地模型条目（或把它合并进你的全局 AX Code 配置）：

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "openrouter": {
      "models": {
        "openrouter/free": {
          "name": "OpenRouter Free Models Router",
          "tool_call": true,
          "limit": {
            "context": 32768,
            "output": 4096,
          },
        },
      },
    },
  },
}

上方的限制是保守的 AX Code 预算值，不是 OpenRouter 授予的权利。然后连接并验证合并后的模型目录：

ax-code providers login openrouter
ax-code models openrouter
ax-code run --model openrouter/openrouter/free "Inspect this repository without editing it and identify its test command."

重复的 openrouter 是有意的：第一段是 AX Code 提供商 ID，openrouter/free 是 OpenRouter 所期望的模型 ID。免费路由器的可用性和选择会随请求变化；见 OpenRouter 的免费路由器文档。

如何使用外部免费 API 目录

awesome-free-llm-apis 有助于发现当前优惠，但它不是 AX Code 的兼容性或背书列表：

支持的提供商与模型中的提供商有默认的 AX Code 设置预设。
仅仅出现在 models-snapshot.json 中的提供商有注册表支持，并不一定为默认设置流程做了精选。
当另一项服务暴露兼容的 OpenAI 或 Anthropic 端点时，可以通过自定义与网关提供商工作。
“OpenAI 兼容”对编程代理是必要的，但并不充分。所选模型还需要流式文本响应，以及可靠的工具/函数调用。
第三方列表中的提供商名称、模型 ID、免费配额、区域和账户要求可能过时。在依赖它们之前，请对照提供商官方的价格、模型和速率限制页面核验。

在本页的审阅日期，该目录点名的服务与 AX Code 的对应关系如下：

AX Code 关系	目录中的服务	含义
默认设置预设	Google Gemini（`google`）、Groq（`groq`）、OpenRouter（`openrouter`）、Hugging Face（`huggingface`）、UnoRouter（`unorouter`）	在正常的提供商设置流程中可见，并已在上方说明。
有注册表支持，但不是默认预设	Mistral（`mistral`）、Cohere（`cohere`）、Zhipu AI（`zhipuai`）、AnyAPI（`anyapi`）、Cerebras（`cerebras`）、NVIDIA NIM（`nvidia`）、Cloudflare Workers AI（`cloudflare-workers-ai`）	捆绑注册表中存在元数据和适配器，但该提供商不属于精选的默认设置流程。显式配置并不能保证某个免费模型支持代理工具。
仅自定义协议	Api.Airforce、Kluster AI、LLM7.io、Pollinations AI	没有 AX Code 预设。只有当其当前 API 与自定义提供商契约兼容时，才配置确切的端点和模型。

特别是，github-copilot 预设并不是某些目录所列出的 github-models API。不要用一个提供商 ID 或凭据流程替换另一个。zai 和 zhipuai 通用 API 从 GLM-5.3 开始；更旧的 GLM 3、 GLM 4、GLM-5 和 GLM-5.2 SKU 仍然被过滤掉。

安全评估实践

先用公开或一次性的仓库测试。托管提供商或网关会收到发送到其 API 的提示和代码上下文。
启用 workspace-write 隔离，或使用 read-only 做仅审阅的冒烟测试。
从一项短任务和一个代理开始。Council、arena、长会话和大型仓库可能消耗许多请求，并迅速触及免费层限制。
用 ax-code providers login 或环境变量存放凭据；绝不要把 API 密钥提交到 ax-code.json。
把 429 和暂时不可用当作正常的免费层约束。等待提供商的重试窗口，或选择另一个当前列出的免费模型。