Русский · English · 简体中文

FreeNIMAPI

用一个本地兼容层，把 NVIDIA NIM 接入常用 AI 编程智能体。
为 Codex 提供 Responses，为 Claude Code 提供 Messages，为 Hermes 与 OpenCode 提供 Chat Completions。

快速开始 · 接入编程智能体 · 工作原理 · 验证 · 安全

Important

FreeNIMAPI 是本地代理服务，不是本地运行的模型。兼容层运行在你的电脑上，但模型推理由 NVIDIA 托管服务完成，并受试用资格、配额、模型可用性和模型许可证限制。

55/55	3 种协议	4 类客户端	1 个本地地址
本地测试	Chat · Messages · Responses	Hermes · Codex · Claude · OpenCode	`127.0.0.1:3000`

完整目录

FreeNIMAPI 是什么
快速开始
获取 NVIDIA API key
接入 AI 编程智能体
工作原理
支持的 API
模型
真实代理验证
安全
高级配置
已知限制
故障排除
文档
许可证与服务条款

FreeNIMAPI 是什么

不同的 AI 编程智能体使用不同的 API 格式。FreeNIMAPI 以上游 NVIDIA 托管版 Chat Completions 接口为基础，再在本地为每个客户端提供它所需要的格式。

客户端	期望的协议	FreeNIMAPI 提供的路由
Codex	OpenAI Responses	`POST /v1/responses`
Claude Code	Anthropic Messages	`POST /v1/messages`
Hermes Agent	OpenAI Chat Completions	`POST /v1/chat/completions`
OpenCode	Chat Completions 或 Responses	两种路由

FreeNIMAPI 会转换请求、结构化工具调用、工具结果和流式终止事件。NVIDIA API 密钥只保留在代理进程中；编程智能体只接触单独的本地访问密钥。

返回顶部 ↑

快速开始

环境要求

macOS、Linux 或 Windows；
Git；
Node.js 20+；
用于 NVIDIA 托管版 NIM 的 NVIDIA API 密钥。

1. 安装并启动

git clone https://github.com/ForgetMeAI/FreeNIMAPI.git
cd FreeNIMAPI
npm ci
npm run start:guided

启动器会提示你输入 NVIDIA API 密钥，输入内容不会显示在终端中，密钥也不会写入磁盘。随后，代理会在 http://127.0.0.1:3000 启动。请保持该终端窗口打开；按 Ctrl+C 停止。

2. 在第二个终端检查

cd FreeNIMAPI
FREENIM_LOCAL_API_KEY=freenim-local npm run health

PowerShell：

$env:FREENIM_LOCAL_API_KEY="freenim-local"
npm run health

health 检查通过，表示本地网关已经可以接收客户端连接；该检查不会消耗 NVIDIA 配额。

Tip

如果需要唯一的本地客户端密钥，请使用 npm run start:secure。它会分别提示你安全输入 NVIDIA API 密钥和下游客户端密钥，输入内容均不会显示。

返回顶部 ↑

获取 NVIDIA API key

登录 NVIDIA API Catalog。
打开 Settings → API keys。
创建 API 密钥，并将其保存在密码管理器或密钥管理器中。
仅将它粘贴到 npm run start:guided 显示的无回显输入提示中。

关于 NVIDIA_API_KEY 与 NGC key 的官方区别，请阅读 NVIDIA authentication and API keys。

Caution

切勿把 NVIDIA API 密钥粘贴到 Codex、Claude Code、Hermes、OpenCode、项目配置、issue、截图或视频命令中。AI 编程智能体只应获得独立的 FREENIM_LOCAL_API_KEY。

返回顶部 ↑

接入 AI 编程智能体

以下示例假设你以 guided 模式启动服务，并且服务只监听本机回环地址。先在客户端终端中设置独立的本地密钥：

export FREENIM_LOCAL_API_KEY=freenim-local

客户端	Wire API	已测试版本	当前验证状态
Hermes Agent	Chat Completions	0.16.0	scripted transport PASS；live NVIDIA PENDING
Codex	Responses	0.144.2	historical live PASS；fresh scripted PASS
Claude Code	Messages	2.1.169	historical live PASS；fresh scripted PASS
OpenCode	Chat / Responses	1.17.18	historical live Chat PASS；Responses PENDING live

以下状态截至 2026-07-17。验证章节详细说明了 historical、scripted 和 live 的含义。

Hermes Agent · Chat Completions

在隔离的 Hermes profile 中添加如下自定义 provider 配置：

model:
  default: nim-auto
  provider: custom
  base_url: http://127.0.0.1:3000/v1
  api_key: freenim-local
  api_mode: chat_completions

freenim-local 只能用于仅监听本机回环地址的 guided 模式。若代理会暴露到网络，请使用 npm run start:secure 生成唯一的本地密钥。E2E 测试运行器使用的完整隔离配置见 docs/AGENT_E2E.md。

Codex · Responses

将 provider 添加到 $CODEX_HOME/config.toml，通常是 ~/.codex/config.toml。测试时建议使用独立的 CODEX_HOME。

model = "nim-auto"
model_provider = "freenim"

[model_providers.freenim]
name = "FreeNIMAPI"
base_url = "http://127.0.0.1:3000/v1"
env_key = "FREENIM_LOCAL_API_KEY"
wire_api = "responses"
requires_openai_auth = false

FreeNIMAPI 会为 Codex 的模型目录请求返回专用的 ModelInfo 元数据，并将 apply_patch 声明为 custom/freeform 工具。

Claude Code · Anthropic Messages

ANTHROPIC_BASE_URL 必须指向服务器根地址，不能包含 /v1：

不要在 Claude Code 的登录界面中选择任何选项：任意自定义 gateway 并不是通过该菜单配置的。请先按 Ctrl+C 退出，然后把下面的完整代码块粘贴到之后用于启动 claude 的同一个终端。即使你跳过了上面的通用 export FREENIM_LOCAL_API_KEY，此代码块也会自动设置 guided 模式的本地 loopback 密钥：

export FREENIM_LOCAL_API_KEY="${FREENIM_LOCAL_API_KEY:-freenim-local}"
export FREENIM_MODEL="${FREENIM_MODEL:-nim-auto}"
export ANTHROPIC_BASE_URL=http://127.0.0.1:3000
export ANTHROPIC_AUTH_TOKEN="$FREENIM_LOCAL_API_KEY"
export ANTHROPIC_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$FREENIM_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION="$FREENIM_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="FreeNIMAPI / $FREENIM_MODEL"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude --model "$FREENIM_MODEL"

首次启动时仍可能出现主题选择、安全提示以及工作区信任确认，这些都属于正常流程；不应再出现登录方式选择界面。/status 应显示 http://127.0.0.1:3000 和凭据来源 ANTHROPIC_AUTH_TOKEN，/model 中则会出现 FreeNIMAPI / nim-auto。若要使用其他模型，可在运行代码块前设置，例如 export FREENIM_MODEL=minimax-m3。

该接入基于 Claude Code 官方的 LLM gateway 机制实现。Anthropic 不保证非 Claude 模型能够表现出相同的行为。

OpenCode · Chat Completions / Responses

将以下 provider 添加到项目级 opencode.json 或 OpenCode 全局配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "freenim-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "FreeNIMAPI Chat",
      "options": {
        "baseURL": "http://127.0.0.1:3000/v1",
        "apiKey": "{env:FREENIM_LOCAL_API_KEY}"
      },
      "models": {
        "nim-auto": { "name": "FreeNIM nim-auto" }
      }
    },
    "freenim-responses": {
      "npm": "@ai-sdk/openai",
      "name": "FreeNIMAPI Responses",
      "options": {
        "baseURL": "http://127.0.0.1:3000/v1",
        "apiKey": "{env:FREENIM_LOCAL_API_KEY}"
      },
      "models": {
        "nim-auto": { "name": "FreeNIM nim-auto" }
      }
    }
  }
}

选择 freenim-chat/nim-auto 或 freenim-responses/nim-auto。

返回顶部 ↑

工作原理

编程智能体使用自己的接口格式发送请求。
FreeNIMAPI 统一处理系统消息、工具定义、工具结果和流式响应生命周期。
FreeNIMAPI 向 NVIDIA 托管版 Chat Completions 接口发送上游请求。
响应会被转换回 Responses、Messages 或 Chat Completions 格式。
编程智能体执行实际工具，并持续这一循环，直到生成最终回答。

自行部署的 NVIDIA NIM 可能会直接提供更多 API。FreeNIMAPI 专门解决以下场景：使用托管版 API Catalog，同时让不同客户端共用同一个本地入口。

返回顶部 ↑

支持的 API

方法与路由	使用方	已实现能力
`POST /v1/chat/completions`	Hermes、OpenCode、OpenClaw	文本、原生工具调用、多轮续接、本地 SSE
`POST /v1/messages`	Claude Code	`tool_use`、`tool_result`、Anthropic SSE
`POST /v1/messages/count_tokens`	Claude Code	本地估算，不消耗 NVIDIA 配额
`POST /v1/responses`	Codex、OpenCode	function/custom tools、`apply_patch`、严格符合终止事件要求的 SSE
`GET /v1/models`	OpenAI-compatible 客户端	模型别名目录
`GET /v1/models?client_version=…`	Codex	带 freeform `apply_patch` 的 Codex `ModelInfo`
`GET /health`	运维	不暴露 secret 的安全就绪状态
`GET /api/diagnostics`	运维	熔断状态、并发状态和脱敏后的运行信息
`GET /capabilities`	运维	兼容桥的能力信息

完整请求格式见 docs/API.md。

返回顶部 ↑

模型

可用性快照：2026-07-17。

Alias	NVIDIA upstream	状态
`nim-auto`, `gpt-oss-120b`	`openai/gpt-oss-120b`	默认；历史实测中已通过 Codex/OpenCode Chat 验证
`minimax-m3`	`minimaxai/minimax-m3`	候选；曾通过 Claude 工作流实测，但后续工具预检不稳定
`glm-5.2`	`z-ai/glm-5.2`	实验性
`deepseek-v4-flash`	`deepseek-ai/deepseek-v4-flash`	实验性
`deepseek-v4-pro`	`deepseek-ai/deepseek-v4-pro`	可用性尚未验证
`kimi-k2.6`	`moonshotai/kimi-k2.6`	已弃用 / 不支持

nim-auto 只是模型别名，并不代表它会永久可用。NVIDIA 可能调整托管模型目录、配额、接口行为和模型许可证。使用前请查看最新的模型卡。

返回顶部 ↑

真实智能体验证

仅有 200 OK，或模型声称“我已修复代码”，都不能证明编程智能体真的能正常完成任务。FreeAPI 测试规范要求使用实际安装的客户端，并观察其真实的工具执行过程：

01	02	03	04	05	06	07
RED	检查项目	真实工具事件	修改项目代码	GREEN	精确 `PROOF.txt`	独立离线验证

在编程智能体运行前后，系统都会计算受保护测试和 package.json 的哈希值。只有同时满足正确的 failure → edit → green 顺序、客户端终止事件，以及智能体进程停止后的独立测试，才能判定为 PASS。

如实记录的验证矩阵

客户端 / 接口	真实客户端的脚本化传输测试	NVIDIA 原生模型实测
Hermes 0.16.0 / Chat	PASS	PENDING
Codex 0.144.2 / Responses	PASS	HISTORICAL PASS · GPT-OSS-120B
Claude Code 2.1.169 / Messages	PASS	HISTORICAL PASS · 使用别名 `nim-auto`，历史上归因于 MiniMax M3；报告未记录准确的上游模型 ID；新的 GPT-OSS 测试未完成 proof/final
OpenCode 1.17.18 / Chat	PASS	HISTORICAL PASS · GPT-OSS-120B
OpenCode / Responses	PASS	PENDING

Scripted 测试可以验证客户端配置、接口转换、工具执行和产物校验，但不能证明原生模型本身的能力。历史实测早于规范化的 FAAS v1.0 标准，因此不会被追溯认定为当前的 N4 PASS。HISTORICAL PASS 来自本地保留的旧版报告；原始报告包并未公开，因此仅凭公共仓库无法独立复核这些状态。

# 55 local unit/integration tests; no network or credentials
npm test

# Real installed clients + deterministic transport
npm run test:agents:mock

# Live NVIDIA endpoint matrix; requires NVIDIA_API_KEY
npm run test:live

# Live coding-agent E2E; requires NVIDIA_API_KEY
npm run test:agents

# Three-language parity and link checks
npm run check:readme

公开的脱敏快照：docs/evidence/agent-qualification-2026-07-17.json。方法与限制：docs/VERIFICATION.md。

返回顶部 ↑

安全

Secret	存放位置	发送位置
`NVIDIA_API_KEY`	仅存在于 FreeNIMAPI 进程的环境变量中	发送到配置的 `NVIDIA_BASE_URL`；默认是 NVIDIA 官方托管接口
`FREENIM_LOCAL_API_KEY`	本地客户端与代理	发送到配置的 FreeNIMAPI 地址；默认是本机回环地址

不会自动加载 .env；
默认拒绝浏览器跨域来源；
默认情况下，未设置独立本地密钥时禁止监听非回环地址；
不会记录提示词、工具结果、上游请求或响应正文以及任何凭据；
限制重试次数、响应大小、请求时限和并发量；
E2E 客户端在不含 NVIDIA 密钥的干净环境中运行；
不提供多账户轮换、绕过配额、Cookie 池或泄露密钥的工作流。

Warning

freenim-local 只适用于 127.0.0.1。如果要从网络访问，请使用 npm run start:secure、TLS 与你自己的访问控制。如果修改 NVIDIA_BASE_URL，上游密钥会发送到新的主机，因此只能填写可信接口。FREENIM_ALLOW_UNAUTHENTICATED_REMOTE=true 会主动关闭远程监听保护，不建议启用。

完整威胁模型见 docs/SECURITY.md。

返回顶部 ↑

高级配置

变量	默认值	用途
`HOST`	`127.0.0.1`	监听地址
`PORT`	`3000`	本地端口
`NVIDIA_BASE_URL`	`https://integrate.api.nvidia.com/v1`	NVIDIA 托管上游接口
`NIM_DEFAULT_MODEL`	`nim-auto`	默认模型别名
`NIM_TIMEOUT_MS`	`120000`	完整请求超时时间
`NIM_MAX_RETRIES`	`2`	可重试错误的重试次数
`NIM_MAX_CONCURRENCY`	`1`	上游并发生成数
`FREENIM_CORS_ORIGINS`	空	允许的浏览器来源
`FREENIM_LOCAL_API_KEY`	空	独立下游身份验证
`FREENIM_ALLOW_UNAUTHENTICATED_REMOTE`	`false`	危险的远程认证保护开关；不建议启用
`NIM_TEXT_TOOL_FALLBACK`	`false`	文本回退；真实智能体验证时禁止启用

在 CI 或密钥管理器中，可以通过环境变量传入 NVIDIA_API_KEY 和唯一的 FREENIM_LOCAL_API_KEY，再运行 npm start。请先执行 npm run doctor。

返回顶部 ↑

已知限制

NVIDIA API Catalog 提供的是试用和评估服务，不承诺生产级 SLA，也不等于“永久免费”。
托管模型可能响应较慢，配额也可能调整，并且可能暂时无法使用原生工具调用。
下游 SSE 要等完整的上游响应返回后才会生成，因此首个 token 的延迟可能等于 NVIDIA 完成整次生成的时间。
当前兼容层仅支持文本，不会转换图像、文档、签名思考块、托管网页搜索、MCP 命名空间或计算机操作项目。
服务端不保存 previous_response_id；下一轮 Responses 请求必须携带所需的对话项目。
count_tokens 只是粗略的本地估算。
模型出现在目录中，并不能证明它能正确使用工具。

用于生产环境前，需要采用单独的商业接口，并重新验证每组精确的 客户端 × 模型 × 协议 组合。

返回顶部 ↑

故障排除

现象	检查项
`health` 返回 `401`	两个终端必须使用同一个 `FREENIM_LOCAL_API_KEY`
Claude Code 无法连接	`ANTHROPIC_BASE_URL` 不能包含 `/v1`
Codex 看不到模型或 tools	`base_url` 必须以 `/v1` 结尾，并设置 `wire_api = "responses"`
智能体只输出文字，不调用工具	当前模型未生成结构化工具调用；这属于模型或预检失败
响应非常慢	试用版上游响应可能耗时数分钟；请检查诊断信息和当前模型状态
修改监听地址后请求失败	先恢复为回环地址，再通过 `npm run doctor` 检查认证和 CORS

npm run doctor
FREENIM_LOCAL_API_KEY=freenim-local npm run health

如果问题可以复现，请创建 issue，但不要附带密钥、Cookie、完整提示词日志或私人路径。

返回顶部 ↑

文档

文档	用途
俄语版快速开始	最短安装路径
API reference	路由与 payloads
Architecture	兼容层与数据流
Agent E2E	真实智能体行为测试规范
Verification	矩阵与资格状态
Security	威胁模型与安全运行
公开证据快照	机器可读的脱敏状态

提交 pull request 前：

不得加入真实凭据或未经脱敏的智能体报告；
运行 npm test 与 npm run check:readme；
分别标记协议测试、脚本化客户端测试和上游实测证据；
没有达到目标验证等级的完整证据时，不得提升客户端状态。

返回顶部 ↑

许可证与服务条款

FreeNIMAPI 源代码采用 MIT License。

NVIDIA 托管 API 受 NVIDIA API Trial Terms 约束，每个模型还适用各自的许可证。试用服务仅用于有限的测试和评估，请勿发送机密数据。

FreeNIMAPI 对你有帮助吗？
请为仓库点亮 ⭐，通过 Issues 报告可复现的问题，
并在 @forgetmeai 获取更多实用 AI 工具。

Русский · English · 简体中文 · 返回顶部 ↑

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FreeNIMAPI

FreeNIMAPI 是什么

快速开始

环境要求

1. 安装并启动

2. 在第二个终端检查

获取 NVIDIA API key

接入 AI 编程智能体

工作原理

支持的 API

模型

真实智能体验证

如实记录的验证矩阵

安全

高级配置

已知限制

故障排除

文档

许可证与服务条款

FilesExpand file tree

README.zh-CN.md

Latest commit

History

README.zh-CN.md

File metadata and controls

FreeNIMAPI

FreeNIMAPI 是什么

快速开始

环境要求

1. 安装并启动

2. 在第二个终端检查

获取 NVIDIA API key

接入 AI 编程智能体

工作原理

支持的 API

模型

真实智能体验证

如实记录的验证矩阵

安全

高级配置

已知限制

故障排除

文档

许可证与服务条款