freellmapi CLI 实战一条命令为 16 编码 Agent 接入 FreeLLMAPI 统一网关【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi导读freellmapi是 FreeLLMAPI 网关的官方命令行配置工具只需一条命令就能让 Claude Code、Codex、Cline、Aider、Goose 等 16 种主流编码 Agent 与 IDE 指向你正在运行的 FreeLLMAPI 网关并自动读取网关实时下发的模型目录按每种工具各自的配置文件格式写入对应配置。读完本文你将掌握该 CLI 的全部命令与参数、模型选择与校验的底层逻辑、非破坏性配置合并与凭据安全机制以及如何用doctor诊断配置了却路由不到网关这类隐蔽问题。为什么需要这个 CLIFreeLLMAPI 把 30 免费 LLM 提供商、600 免费模型端点统一收敛到单一 OpenAI 兼容/v1端点之后剩下的最后一公里是让每个编码 Agent 都指向这个端点。而每种工具读取配置的方式完全不同Claude Code 读~/.claude/settings.json的env块Codex 读~/.codex/config.toml的[model_providers]表Cline 读~/.cline/data/settings/providers.jsonOpenCode/Kilo 读 JSON 配置Goose 读custom_providers目录……手工逐一配置既繁琐又容易踩坑。freellmapi的核心设计是生成器读取网关真实服务的模型再写出每种工具期望的配置见 cli/src/tools.ts 中 16 个generate()实现。CLI 依赖只有jsonc-parser与yaml两个解析库见 cli/package.json通过npx运行无需安装步骤、无需注册账号统一 API Key 来自 FreeLLMAPI 仪表盘或桌面应用托盘的 popover。快速开始前置条件本机已运行 FreeLLMAPI 网关安装方式见仓库 docs/install.mdNode.js 版本满足要求详见下文运行环境。以接入 Claude Code 为例一条命令即可完成配置npx freellmapi setup-claude --url http://localhost:3001 --api-key your-key命令执行时 CLI 会做三件事以Authorization: Bearer your-key请求url/v1/models?availabletrue拉取网关当前实际可用的模型目录实现在 cli/src/index.ts 的catalog()依据目录挑选默认模型默认为auto即让网关路由按请求动态选择最优模型详见下文模型选择机制把生成内容合并进~/.claude/settings.json而非整体覆盖。如果不想在命令行里写明文 Key也可以不传--api-key——当终端是 TTY 时 CLI 会交互式地静默提示输入输入内容不回显实现在promptForKey()非 TTY 环境则直接报错并提示改用参数或环境变量。命令总览命令目标工具说明setup-claudeClaude Code写入~/.claude/settings.json的env块setup-codexCodex CLI写入~/.codex/config.toml的 provider 表setup-clineCline写入~/.cline/data/settings/providers.jsonsetup-continueContinue写入~/.continue/config.yamlsetup-aiderAider写入~/.aider.conf.ymlsetup-opencodeOpenCode写入~/.config/opencode/opencode.jsonsetup-gooseGoose写入自定义 provider 配置与config.yamlsetup-qwenQwen Code写入~/.qwen/settings.json与.envsetup-rooRoo Code写入~/.roo/freellmapi.json配置文件setup-kiloKilo Code写入~/.config/kilo/kilo.jsoncsetup-crushCrush写入~/.config/crush/crush.jsonsetup-dshDeepSeek Harness (dsh)写入$DSH_HOME/settings.yaml与.envsetup-mimoMiMo Code (mimo)写入 MiMo 全局配置目录的config.jsonsetup-atomcodeAtomCode写入~/.atomcode/config.tomlsetup-cursorCursor仅输出操作指引不写文件setup-generic任意 OpenAI 兼容客户端仅输出环境变量与 curl 示例launchClaude Code子进程注入凭据运行claude不落盘launch-codexCodex子进程注入凭据与 provider 覆盖运行codexlist—打印受支持工具及其协议、base URL 支持方式doctorClaude Code / Codex诊断请求是否真正到达本网关完整的工具元数据id、协议、base URL 形态、命令名同时维护在 cli/tools.json 中。setup-*命令的注册表在 cli/src/tools.ts 的metadata常量里除setup-claude走 Anthropic Messages 协议、baseUrlSupport为root网关根地址外其余工具均为 OpenAI 兼容协议、指向/v1。参数详解参数含义默认值/说明--url URL网关 base URL文档示例默认http://localhost:3001当前仓库源码 cli/src/index.ts 的解析默认值为http://localhost:3000生产使用建议始终显式传--url--api-key KEY统一 API Key缺省时 TTY 下交互式静默输入同时支持环境变量--profile NAME生成的 profile/provider 条目名称default仅允许字母、数字、点、下划线、连字符禁止./..及含/的路径穿越值validateProfile()校验--model ID固定具体模型而非目录默认不传时各生成器默认选auto网关侧路由--dry-run只打印 diff不写任何文件布尔开关--timeout MS仅doctor使用/livez探针等待毫秒数默认 5000ms慢速链路可调大环境变量FREELLMAPI_URL与FREELLMAPI_API_KEY可完全替代--url/--api-key适合脚本化场景。参数解析支持--flagvalue与--flag value两种写法且选项可以放在命令之前或之后见 cli/src/index.test.ts 的parseArgs用例。值得一提的健壮性细节--timeout 5s这类笔误会被直接拒绝must be a positive number of milliseconds而不是悄悄回落为默认值缺失选项值也会报错而不是吞掉下一个 flag。各工具的配置细节Claude Codesetup-claude生成器写入~/.claude/settings.jsonprofile 非 default 时写入~/.claude/profiles/name/settings.json核心是env块{ env: { ANTHROPIC_BASE_URL: http://localhost:3001, ANTHROPIC_AUTH_TOKEN: your-key, ANTHROPIC_MODEL: auto, ANTHROPIC_DEFAULT_OPUS_MODEL: auto, ANTHROPIC_DEFAULT_SONNET_MODEL: auto, ANTHROPIC_DEFAULT_HAIKU_MODEL: auto, CLAUDE_CODE_AUTO_COMPACT_WINDOW: 模型上下文窗口, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: 1 } }该文件被标记为sensitive写入时权限为0600。上下文窗口取自模型目录的context_window/context_length字段缺失时回退 128000。注意launch命令使用的环境构建逻辑claudeLaunchEnv则不同窗口未发布时不设置CLAUDE_CODE_AUTO_COMPACT_WINDOW让 Claude Code 用自身默认值——因为编造一个错误的窗口值会导致过早或过晚的自动压缩。Codex CLIsetup-codexCodex 只读~/.codex/config.toml一个文件命名 profile 也是同一文件里的[profiles.NAME]表。生成内容用# freellmapi:start/end标记块包裹包含[model_providers.freellmapi]表# freellmapi:start model auto model_provider freellmapi model_context_window 128000 model_auto_compact_token_limit 115200 tool_output_token_limit 20000 [model_providers.freellmapi] name FreeLLMAPI base_url http://localhost:3001/v1 wire_api responses env_key FREELLMAPI_API_KEY requires_openai_auth false # freellmapi:end关键点Key 不写入 config.toml而是通过env_key FREELLMAPI_API_KEY引用环境变量运行codex前需export FREELLMAPI_API_KEYyour-key。model_auto_compact_token_limit取上下文窗口的 90%至少 16000。Cline / Continue / AiderCline写入~/.cline/data/settings/providers.json声明一个openai-compatibleprovider协议openai-chat、开启streaming与tools能力、contextWindow同步自目录apiKey直接写入sensitive。updatedAt字段固定为确定性时间戳保证重复执行幂等。Continue写入~/.continue/config.yaml模型条目通过apiKey: ${{ secrets.FREELLMAPI_API_KEY }}引用 Continue 密钥库不落盘明文 Key需先在 Continue 中添加该 secret。Aider写入~/.aider.conf.yml含openai-api-base、openai-api-keysensitive 直写与model: openai/id。也提供了纯环境变量替代方案OPENAI_API_BASE... OPENAI_API_KEY... aider --model openai/id。OpenCode 系OpenCode / Kilo / MiMo Code三者都基于 AI SDK 的ai-sdk/openai-compatible配置结构同源OpenCode~/.config/opencode/opencode.json为目录中每个可用模型生成models条目含 context/output 限额Key 用{env:FREELLMAPI_API_KEY}占位符Kilo Code~/.config/kilo/kilo.jsonc结构类似模型条目带tool_call: trueMiMo Code$XDG_CONFIG_HOME/mimocode/config.json或$MIMOCODE_HOME/config下与 OpenCode 同构默认模型命名为freellmapi/id因此会把选中的模型放在 provider 自身models映射的最前面。MiMo 没有MIMOCODE_API_KEY之类的环境变量兜底Key 必须走配置内的{env:...}替换。Goose / Qwen Code / Roo Code / CrushGoose写入两份文件——~/.config/goose/custom_providers/freellmapi.json自定义 providerengine: openai、api_key_env: FREELLMAPI_API_KEY、base_url、每个模型的context_limit、supports_streaming、preserves_thinking与~/.config/goose/config.yamlGOOSE_PROVIDER/GOOSE_MODEL。Qwen Code写入~/.qwen/settings.json模型列表 security.auth.selectedType: openai与~/.qwen/.envsensitive直写FREELLMAPI_API_KEY...。生成器额外提示Qwen 原生 Gemini 模式也可用地址为根/v1betaGEMINI_API_KEY。Roo Code写入~/.roo/freellmapi.jsonproviderProfiles.apiConfigs.freellmapi含openAiBaseUrl、openAiApiKey、openAiModelId需在 Roo Code 设置autoImportSettingsPath指向该文件。Crush写入~/.config/crush/crush.json模型条目成本字段全部置 0cost_per_1m_in/cost_per_1m_out等api_key用$FREELLMAPI_API_KEY引用环境变量。DeepSeek Harnesssetup-dshdsh 读取单一 YAML 设置文档$DSH_HOME/settings.yaml默认~/.dsh。每个 provider 是llm-pi-ai.providers下的一个 route声明api: openai-completions、baseURL、完整models列表Key 通过apiKeyEnv: FREELLMAPI_API_KEY引用——dsh 会把$DSH_HOME/.env0600 权限作为用户环境层加载因此 Key 写入该文件后下次请求即可生效无需手动 export。非 default profile 会生成freellmapi-name形式的第二个 routedsh 中 route id 永久、必须小写并在模型选择器中作为额外选项出现不会夺走默认模型。设置文件支持热重载运行中的 dsh 在下一个请求时即可感知。若模型需支持视觉可在 route 的 models 中补充input: [text, image]。Cursorsetup-cursor与通用客户端setup-generic这两个生成器不写任何文件只输出指引/环境变量Cursor 的模型流量经过其云端服务本地 localhost 无法从 Cursor 直达。正确做法是把网关通过可信 HTTPS 隧道暴露为公网地址然后在 Cursor Settings → Models 中启用 Override OpenAI Base URL 并填入public-url/v1。注意该覆盖是全局生效的切换回内置 provider 前要记得关闭如客户端无法设置 Authorization 头建议使用可单独吊销的 URL Token。通用 OpenAI 兼容客户端输出三个环境变量OPENAI_BASE_URL、OPENAI_API_KEY、OPENAI_MODEL外加一条可直接运行的 curl 验证命令POST url/v1/chat/completions。零凭据落盘的 launch 系列命令setup-*把 Key 写进配置文件部分标记 sensitive 以 0600 权限存储而launch与launch-codex完全不写盘凭据只在本次运行注入子进程环境。freellmapi launch的底层实现claudeLaunchEnv见 cli/src/index.ts先删除子进程环境里已有的ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN确保用户真实 Anthropic 凭据不会泄漏给网关测试 cli/src/index.test.ts 专门断言了这一点设置ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN即统一 Key、ANTHROPIC_MODEL及三个ANTHROPIC_DEFAULT_*_MODEL启用CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY让 Claude Code 自动发现网关模型指定--profile时通过CLAUDE_CONFIG_DIR指向~/.claude/profiles/name目录不存在则报错并提示先运行setup-claude --profile子进程继承 stdio 交互运行包装进程忽略 SIGINT把终端信号留给前台子进程、转发 SIGTERM并透传子进程退出码。freellmapi launch-codex则以-c参数把整个[model_providers.freellmapi]覆盖注入codex命令wire_apiresponses、env_keyFREELLMAPI_API_KEY、requires_openai_authfalseKey 放入子进程环境变量同样不写盘。模型选择机制auto、固定模型与配额语义理解模型选择机制是正确使用本 CLI 的关键其核心逻辑在 cli/src/models.ts目录拉取分两次CLI 先请求?availabletrue只返回当前可服务模型再尽力请求不带过滤的完整目录。原因是模型不在可用目录里可能是不存在也可能是存在但此刻超配额/冷却中。只有未过滤目录能区分这两种情况——把配额问题误报成模型拼写错误是本 CLI 刻意要消除的歧义catalogs()与resolvePinnedModel()的注释详述了这一点。若未过滤目录拉取失败会降级使用过滤目录并显式警告用户判定口径被削弱。生成器的默认模型是auto让网关路由逐请求选优这是长生命周期配置文件最合理的默认。primaryModel()优先auto其次第一个available ! false的模型且永远不会意外落到fusion多模型扇出。--model校验针对未过滤目录固定一个已注册但当前不可服务的模型时会警告registered but not currently available (out of quota, cooling down, or its key is disabled). Launching anyway——仍然继续启动因为路由可能在会话中途恢复该模型而真正不存在的 id 会抛UnknownModelError并给出最多 5 条相似 id 建议。launch 系列的默认与 setup 刻意不同launch默认固定第一个可服务的具体模型而非auto因为会话级ANTHROPIC_MODEL需要一个可复现的具名模型。安全性非破坏性合并、备份与最小权限每个生成器都是非破坏性的实现在 cli/src/config-files.ts结构合并而非覆盖JSON/JSONC 用jsonc-parser按路径深度合并保留原有注释与格式选项YAML 用yaml库在解析后的 Document 上打补丁用户文件的注释、键序、引号风格全部保留undefined值可删除过期键TOML 则把生成的根键插到第一个[table]之前、生成的表追加到末尾并用# freellmapi:start/end标记块隔离自家内容重复运行可原地替换旧块。写入前备份目标文件已存在时先复制为路径.backup-ISO时间戳再写入且采用两阶段提交——所有目标文件先全部读取合并任何一个失败就中止整批不会出现写了一半的残缺状态。敏感文件 0600标记sensitive的文件含 Key 的配置文件、.env目录以0700创建、文件以0600写入。--dry-run先看再写只打印统一 diff 格式的变更新建文件逐行既有文件从首个差异行起-/对照含 line N 标记不写任何文件。doctor诊断请求到底到没到网关freellmapi doctor [tool…]是排查路由问题的专用命令不传工具时默认检查claude与codex实现在 cli/src/doctor.ts。它的核心洞察这种故障在服务端无日志可查请求根本没到网关所以必须在继承用户会话环境的本地进程里按每种工具自己的解析规则还原其有效 base URL再探测网关/livez。它返回五种判定判定含义OK routed工具实际到达本网关且健康WARN shadowed有低优先级配置设置了别的 URL但被高优先级层覆盖了如 launch 进程注入覆盖了 settings.json或 settings 的 env 块覆盖了 shell 导出WARN degraded路由正确、网关身份无误但网关报status: unavailable数据库或加密密钥故障503此刻无法服务FAIL elsewhere工具到达的是别的端点不同主机或同一端口但响应体不像本网关FAIL unreachable有效端点无响应如 ECONNREFUSED? unknown完全无配置工具将走厂商默认端点或传入 doctor 未建模的工具实现细节值得注意Claude Code 的 base URL 层级高→低为系统托管目录/etc/claude-code及managed-settings.d/*.json按字母序倒序合并各平台路径不同→ 项目.claude/settings.local.json→ 项目settings.json→$CLAUDE_CONFIG_DIR/用户settings.json→ 进程环境ANTHROPIC_BASE_URL。settings 的 env 块在启动时会写回进程环境、覆盖 shell 导出所以进程环境反而是最低层cli/src/doctor.test.ts 专门锁定了这一易错顺序。Codex 解析的是model_provider选中的那个[model_providers.name]表的base_url兼容点式键写法而非文件中第一个出现的 base_url。/livez探测把身份识别与健康分开响应含status字符串version字符串uptime_s数字即认定为网关status值为ok且 2xx 才健康。网关真的会在故障时返回{status:unavailable,...}的 503此时仍能被识别为本网关但病了degraded而不是误判为其他服务。URL 归一化会忽略尾斜杠、/v1后缀、主机大小写和 query/fragment但保留路径前缀与路径大小写避免同一主机不同挂载点被混为一谈。退出码可脚本化全部routed时为 0否则为 1适合作为 CI/启动前置检查--timeout MS可在慢速链路上调大探测等待。运行环境Node.js 20.18.0 25.0.0见 cli/package.json 的engines字段源码使用原生fetch与AbortSignal.timeout。一个正在运行的 FreeLLMAPI 网关安装与启动见 docs/install.md。无需全局安装npx freellmapi ...即用即走也支持npm i -g freellmapi后直接调用freellmapi。进一步阅读各编码 Agent 接入网关的完整指南docs/clients/01-agent-clients.mdCLI 源码入口与参数解析cli/src/index.ts16 个工具的生成器实现cli/src/tools.ts配置合并、备份与 dry-run 实现cli/src/config-files.tsdoctor 诊断实现与测试cli/src/doctor.ts、cli/src/doctor.test.tsCLI 参数与启动行为测试cli/src/index.test.ts工具元数据清单cli/tools.json【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考