NVIDIA-OpenCode-免费模型使用指南

一、准备工作：获取 NVIDIA API Key

1. 打开浏览器访问 https://build.nvidia.com
2. 注册/登录 NVIDIA 开发者账号（直接用 Google/Microsoft/GitHub 账号登录即可）
3. 登录后进入 API Keys 页面：https://build.nvidia.com/settings/keys
4. 点击 "Generate New API Key" 生成密钥
5. 复制密钥（格式为 nvapi-xxxxxxxx...，妥善保存，关闭页面后不可再查看）

查询当前可用免费模型列表： https://build.nvidia.com/models?filters=nimType%3Anim_type_preview

二、通过 /connect 命令快速配置（推荐新手）

这是最简单的方式，OpenCode 会自动帮你配置密钥和模型。

1. 打开终端，进入你的工作目录，启动 OpenCode：

opencode

1. 在 OpenCode 界面中，输入 /connect 命令：

/connect

1. 在接下来的列表中，选择 NVIDIA（可以按 j/k 键或方向键选择，按回车确认）
2. 输入你的 NVIDIA API Key：

┌ API key│
│ nvapi-你的密钥粘贴在这里
└ enter

1. 输入完成后，输入 /models 查看所有可用模型：

/models

1. 使用方向键选择你想要的 NVIDIA 模型（如 nemotron-3-super-120b-a12b），按回车确认

三、通过配置文件手动配置（推荐进阶用户）

如果你想固定使用某个模型，或者想同时配置多个模型，可以修改配置文件。

3.1 找到配置文件位置

• 项目级配置：./opencode.json 或 .opencode/opencode.json（项目根目录）
• 全局配置：~/.config/opencode/opencode.json（所有项目通用）

新手建议先创建项目级配置，在项目根目录下执行：

Windows (PowerShell):

New-Item -Path .\opencode.json -Value '{"$schema":"https://opencode.ai/config.json"}' -ItemType File

Mac/Linux:

touch opencode.json
echo '{"$schema":"https://opencode.ai/config.json"}' > opencode.json

3.2 编辑配置文件

在 opencode.json 中添加 NVIDIA 配置，推荐完整配置如下：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nvidia/nemotron-3-super-120b-a12b",
  "provider": {
    "nvidia": {
      "options": {
        "apiKey": "nvapi-你的API密钥粘贴在这里"
      }
    }
  }
}

关键字段说明：

• model：默认主模型，格式为 nvidia/模型ID
• small_model（可选）：设置小模型用于标题生成等轻量任务

{
  "small_model": "nvidia/mistral-small-4-119b-2603"
}

3.3 配置自定义模型（可选）

如果你在 NVIDIA 网站上看到了 OpenCode 没有预加载的模型，可以手动添加：

{
  "provider": {
    "nvidia": {
      "models": {
        "在/model页面看到的模型ID": {
          "name": "你喜欢的模型名称"
        }
      }
    }
  }
}

示例：

{
  "provider": {
    "nvidia": {
      "models": {
        "nemotron-3-ultra-550b-a55b": {
          "name": "Nemotron 3 Ultra (550B)"
        }
      }
    }
  }
}

3.4 使用环境变量配置（更安全，不把 Key 写在配置文件里）

Windows (PowerShell):

$env:NVIDIA_API_KEY="nvapi-你的密钥"
opencode

Windows (CMD):

set NVIDIA_API_KEY=nvapi-你的密钥
opencode

Mac/Linux:

export NVIDIA_API_KEY="nvapi-你的密钥"
opencode

四、验证配置是否成功

1. 启动 OpenCode 后，输入 /models 命令
2. 查看列表里是否出现 NVIDIA 相关的模型
3. 选择一个模型（如用方向键选中 nvidia/nemotron-3-super-120b-a12b）
4. 尝试发送一条消息测试：你好，请简单介绍一下你自己

如果模型正常回复，说明配置成功。

五、推荐 NVIDIA 免费模型速查表

以下是在 https://build.nvidia.com/models?filters=nimType%3Anim_type_preview 页面上标有 "Free Endpoint"（免费端点）的模型，以及它们在 OpenCode 中的使用 ID：

注意：模型 ID 中 / 分割符前是 nvidia（OpenCode 的 provider 名称），后面部分是你在 NVIDIA build 页面看到的精确模型 slug。如果模型名包含下划线 _，在 OpenCode 中保持原样。

六、切换和选择模型

方法 1：OpenCode 内切换（运行时）

在 OpenCode 中输入：

/models

用方向键选择模型，回车确认。

方法 2：CLI 参数指定（无需改配置文件）

# 直接指定模型启动，配置文件中的 model 字段会被覆盖
opencode -m nvidia/nemotron-3-ultra-550b-a55b

七、限制和注意事项

八、本地部署（NIM - 无需联网）

如果你有本地 GPU 并想离线使用，可以部署 NVIDIA NIM 本地服务：

1. 安装 NVIDIA NIM：参考 https://docs.nvidia.com/nim/
2. 配置 OpenCode（在 opencode.json 中）：

{
  "provider": {
    "nvidia": {
      "options": {
        "baseURL": "http://localhost:8000/v1"
      }
    }
  }
}

1. 启动本地 NIM 服务后，像平时一样在 OpenCode 中选择 NVIDIA 模型即可。

九、同时使用多个 NVIDIA 模型

如果你需要不同的 Agent 使用不同的 NVIDIA 模型，可以这样配置：

{
  "agent": {
    "coder": {
      "model": "nvidia/deepseek-v4-flash",
      "mode": "subagent",
      "description": "编程专用 Agent",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "planner": {
      "model": "nvidia/nemotron-3-ultra-550b-a55b",
      "mode": "subagent",
      "description": "规划专用 Agent",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    }
  },
  "model": "nvidia/nemotron-3-super-120b-a12b"
}

这样：

• 主会话使用 nemotron-3-super-120b-a12b
• 刷 @coder 时使用 deepseek-v4-flash
• 刷 @planner 时使用 nemotron-3-ultra-550b-a55b

十、常见问题排查

Q: 提示 Provider not found: nvidia

• 解决：确保 opencode.json 顶部的 "$schema" 字段存在且格式正确；重启 OpenCode（配置热加载有限制，建议退出重建）

Q: 输入 /models 没有 NVIDIA 模型

• 解决：确认 API Key 已正确输入；重启 OpenCode；检查网络是否能访问 integrate.api.nvidia.com

Q: 模型返回错误响应

• 解决：检查是否选中的是 NVIDIA 页面上仍标有 "Free Endpoint" 的模型；部分模型可能已转为付费

Q: 如何查看当前已用 token 数量？

• 在 OpenCode 中模型回复时，底部一般会显示 Input: XXX tokens, Output: YYY tokens

Q: 配置文件写错了导致 OpenCode 无法启动？

• 解决：删除有问题的 opencode.json 文件重新来；或设置环境变量 OPENCODE_DISABLE_PROJECT_CONFIG=1 来跳过项目配置启动

参考链接

• NVIDIA 免费模型列表：https://build.nvidia.com/models?filters=nimType%3Anim_type_preview
• OpenCode 官方文档：https://opencode.ai/docs/
• OpenCode Providers 文档：https://opencode.ai/docs/providers
• NVIDIA NIM 本地部署文档：https://docs.nvidia.com/nim/
• OpenCode Discord 社区：https://opencode.ai/discord