在 OpenCode 中使用免费 LLM API
OpenCode 是一款面向终端和桌面的开源编程智能体。它接受任何兼容 OpenAI 的提供商。本指南通过 FreeLLMAPI 将 OpenCode 连接到免费模型。一条命令即可写入配置并保存密钥。
代码、模型名称和目录中的实时标签以英文显示。
第 1 步:安装 FreeLLMAPI
FreeLLMAPI 是一个开源网关。它在您的计算机上通过 Docker 运行,并通过一个密钥汇集 45 个提供商的免费套餐。
在 macOS 或 Linux 上安装
curl -fsSL https://freellmapi.co/install.sh | bash打开 http://localhost:3001。在密钥页面至少添加两个免费提供商密钥。Google AI Studio 和 Groq 各可在几分钟内获得一个免费密钥。从同一页面复制您的统一密钥。
第 2 步:用一条命令连接 OpenCode
一条命令
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key> --dry-run
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key>
opencode该命令执行三项操作:
- 它会添加一个
freellmapi提供商,位于~/.config/opencode/opencode.json中。该提供商会列出实时目录中的模型及其上下文限制。 - 它会将
freellmapi/auto设为默认模型。 - 它会将密钥保存到 OpenCode 的凭据文件
~/.local/share/opencode/auth.json中。无论是在 CLI 还是桌面应用中,您都不需要环境变量。
命令在写入之前会先创建备份。它会合并新的提供商,因此您的其他提供商会保留。如果设置了 XDG_CONFIG_HOME 或 XDG_DATA_HOME,该命令会使用这些文件夹。
在开始长时间任务之前,请确认网关现在可以处理请求。此调用仅列出当前有可用密钥的模型:
检查哪些模型已就绪
curl "http://localhost:3001/v1/models?execution_status=ready" \
-H "Authorization: Bearer <unified-key>"状态为 exhausted 的模型已配置密钥,但所有密钥目前都已达到限制。当冷却时间结束后,此状态会清除。运行 npx freellmapi doctor,确认客户端的请求能够到达网关。仪表板的请求日志会显示来自 OpenCode 的每次调用。X-Routed-Via 响应标头会说明每个请求由哪个提供商和模型应答。如果请求发生了故障切换,X-Fallback-Trail 标头会列出每个失败的跳转及其原因。
手动设置:opencode.json 提供商配置块
如需手动设置,请将此配置块添加到 ~/.config/opencode/opencode.json,或添加到项目中的 opencode.json。OpenCode 使用 @ai-sdk/openai-compatible 处理 /v1/chat/completions 端点。
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"model": "freellmapi/auto",
"provider": {
"freellmapi": {
"npm": "@ai-sdk/openai-compatible",
"name": "FreeLLMAPI",
"options": {
"baseURL": "http://localhost:3001/v1"
},
"models": {
"auto": {
"name": "Auto",
"limit": { "context": 128000, "output": 8192 }
}
}
}
}
}然后添加密钥。启动 OpenCode,运行 /connect,选择 freellmapi 提供商,并粘贴您的统一密钥。/connect 中的提供商 ID 必须与配置中的 ID 一致。运行 /models 选择模型。
limit.context是该模型的最大输入 token 数。limit.output是它可以生成的最大 token 数。- 顶层的
model使用provider/model格式。如果不设置,OpenCode 会保留之前使用的模型。 - 您要使用的每个模型 ID 都必须位于
models映射中。请从GET /v1/models添加更多 ID。
providers 键的 V2 配置格式。文档称,上述 V1 格式仍受支持。FreeLLMAPI 设置命令写入的是 V1 格式。为 OpenCode 选择模型
OpenCode 是一个智能体。它通过工具调用读取文件、编辑文件并运行命令。每个请求都包含系统提示词、工具定义和文件内容。请使用支持工具调用且上下文窗口较大的模型。
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 请求/分钟 1 req/min per model | 是 | 否 |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 请求/分钟 40 RPM | 是 | 是 |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 是 | 是 |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | 是 | 否 |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 请求/分钟 50 请求/天 50 req/day account-wide (1,000 after a $10 purchase) | 是 | 是 |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 请求/分钟 50 请求/天 Shared rate limit | 是 | 否 |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 请求/分钟 250 请求/天 70,000 令牌/分钟 ~6M | 是 | 是 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | 是 | 是 |
显示 12 个(共 109 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
使用 freellmapi/auto,让路由器为每个请求选择模型。将 auto:smart 或 auto:fast 添加到 models 映射中,可根据智能程度或速度引导请求。您也可以在仪表板上创建命名配置方案后,将其添加,例如 auto:coding。
速率限制与长会话
一次智能体任务可能发送数十个请求。单个免费套餐很快就会在长任务中耗尽。FreeLLMAPI 会统计每个密钥的请求数和 token 数。当某个提供商返回 429 错误时,路由器会将请求发送到链中的下一个模型,会话继续进行。
- 添加四个或更多提供商的密钥。更多提供商意味着每天有更多请求数。
- 将
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch写入 FreeLLMAPI 的.env,以开启上下文交接。模型切换时,下一个模型会收到一段简短说明,告知它正在继续一项任务。 - 粘性会话会将一段对话保持在同一模型上 30 分钟。这样可以保持智能体的一致性。
- 每项任务都开启新会话。较小的上下文每个请求使用的 token 更少。
故障排除
| 问题 | 原因 | 解决方法 |
|---|---|---|
| "Invalid API key",但密钥有效 | 配置中为空的 apiKey 覆盖了 /connect 中的密钥 | 删除 apiKey(位于 options 中),或再次运行 setup-opencode |
| OpenCode 未使用新的提供商 | 未设置顶层的 model | 设置 "model": "freellmapi/auto" |
| 找不到模型 | 该模型 ID 不在提供商的 models 映射中 | 将该 ID 添加到映射中,或再次运行 setup-opencode |
{env:VAR} 密钥为空 | OpenCode 会将未设置的变量替换为空字符串 | 在同一 shell 中导出该变量,或使用 /connect 保存密钥 |
| 工具调用失败 | 该模型的工具调用能力较弱 | 从上表中选择模型 |
| 错误信息:所有模型在 N 次尝试后均已限流 | 所有密钥都已达到限制 | 添加更多提供商的密钥,或等待冷却时间结束 |
常见问题
我可以免费使用 OpenCode 吗?
可以。OpenCode 是开源软件。将其连接到 FreeLLMAPI,作为兼容 OpenAI 的提供商即可。网关会将每个请求发送到免费的提供商套餐,因此推理费用为 $0。
如何在 OpenCode 中添加自定义的兼容 OpenAI 的提供商?
在 opencode.json 中添加一个提供商,将 npm 设置为 @ai-sdk/openai-compatible,并配置 options.baseURL 和 models 映射。然后运行 /connect 保存密钥,运行 /models 选择模型。
哪个免费模型最适合 OpenCode?
请使用支持工具调用且上下文至少为 128K 的模型。本页的表格列出了目前同时满足这两项条件的最强免费模型。使用 freellmapi/auto,让路由器为您选择一个模型。
OpenCode 将 API 密钥保存在哪里?
通过 /connect 添加的密钥会保存到 ~/.local/share/opencode/auth.json。FreeLLMAPI 设置命令会将密钥写入该文件,因此 CLI 和桌面应用都能找到它。
相关指南
- 将 Aider 与免费 LLM API 配合使用
- 将 Codex CLI 与免费模型配合使用
- 如何免费使用 Claude Code
- 最佳免费编程模型 API
- 免费兼容 OpenAI 的 API Base URL
来源
- OpenCode docs: providers (V1 config) (检查于 20 November 2026)
- OpenCode docs: config (检查于 20 November 2026)
- OpenCode docs: migrate from V1 (检查于 20 November 2026)
- FreeLLMAPI CLI generators (检查于 20 November 2026)
- FreeLLMAPI docs: context handoff (检查于 20 November 2026)