OpenCode 配置教程

本教程帮助第一次接触 API 的用户，把 OpenCode 连接到 AruHub。不同版本的菜单名称可能略有不同，请以当前客户端界面为准。

1. 这是什么工具

OpenCode 是一个在终端中运行的 AI 编码助手。终端是输入命令的窗口：Windows 常用 PowerShell 或 WSL 终端，macOS 和 Linux 常用“终端”应用。OpenCode 可以读取当前项目、解释代码并在获得许可后修改文件或运行命令。

本页只介绍如何安装 OpenCode，以及如何把模型请求发送到 AruHub，不介绍复杂的自动化工作流。

2. 适合什么用户

OpenCode 适合希望在命令行里完成代码解释、查错和小范围修改的用户。第一次使用时，建议先在一个没有重要文件的测试文件夹中操作，并逐次确认文件修改和命令执行。

如果你不熟悉终端，也可以照着本页逐步完成。每次只复制当前操作系统对应的命令。

3. 开始前准备

先准备以下内容：

1. 一台 Windows、macOS 或 Linux 电脑。OpenCode 官方建议 Windows 用户优先在 WSL（Windows Subsystem for Linux，Windows 内的 Linux 环境）中使用。
2. 已登录 AruHub，并能打开“我的密钥”。
3. 确认以下三个值：

配置项	应填写的内容
Base URL	https://api.aruhub.com/v1
API Key	登录 AruHub 后，在“我的密钥”页面创建；本文示例只写 sk-xxxxxxxx
模型 ID	从 AruHub 模型价格页、OpenCode 实际加载的模型列表或 AruHub /v1/models 返回结果确认

API Key 相当于账户密码，不要发给其他人，也不要上传到 GitHub、网盘、截图或公开聊天。

Base URL 通常填写到 /v1 为止。不要写成 https://api.aruhub.com/v1/v1，也不要把 /chat/completions 当成 Base URL，除非客户端明确要求完整接口地址。

4. 安装或打开工具

按操作系统选择一种官方安装方式，不需要全部执行。

Windows

官方建议使用 WSL。先按微软说明安装 WSL，然后打开“Ubuntu”或其他 WSL 终端，在该窗口运行：

curl -fsSL https://opencode.ai/install | bash

OpenCode 也提供 Windows 原生安装方式。若你已经使用 Chocolatey，在 PowerShell 中运行：

choco install opencode

若你已经使用 Scoop，在 PowerShell 中运行：

scoop install opencode

macOS

打开“终端”，选择一种方式运行：

curl -fsSL https://opencode.ai/install | bash

已经安装 Homebrew 的用户也可以在终端运行：

brew install anomalyco/tap/opencode

Linux

打开终端运行：

curl -fsSL https://opencode.ai/install | bash

已安装 Node.js 的通用方式

在 PowerShell、WSL 或 macOS/Linux 终端运行：

npm install -g opencode-ai

安装完成后，在同一个窗口检查：

opencode --version

能显示版本号表示命令已安装。若提示找不到命令，先关闭终端并重新打开，再检查安装输出中的 PATH 提示。

5. 创建 AruHub API Key

1. 在浏览器登录 AruHub。
2. 打开“我的密钥”页面。
3. 点击创建密钥，按页面提示填写名称和限制。
4. 创建后复制密钥，并暂时保存在可信的密码管理器中。
5. 本教程用 sk-xxxxxxxx 表示你的密钥；实际配置时必须替换，但不要把真实值发给他人。

ChatGPT 网站账号、OpenCode 账号与 AruHub API Key 不是同一种凭证。

6. 配置 Base URL

OpenCode 当前正式文档使用 JSON 或 JSONC 配置文件。JSONC 是允许写注释的 JSON 格式。

全局配置文件默认位置是：

~/.config/opencode/opencode.json

~ 表示当前用户的主目录。项目根目录中的 opencode.json 只影响该项目，并且会覆盖同名的全局配置。新手建议先使用全局配置，避免在多个位置重复定义。

用文本编辑器打开或新建该文件，写入下面的完整示例。replace-with-model-id 是占位符，下一节会替换：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aruhub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AruHub",
      "options": {
        "baseURL": "https://api.aruhub.com/v1"
      },
      "models": {
        "replace-with-model-id": {
          "name": "AruHub 模型"
        }
      }
    }
  },
  "model": "aruhub/replace-with-model-id"
}

字段含义：provider 是服务提供方配置；npm 指定 OpenAI Chat Completions 兼容适配器；options.baseURL 是接口根地址；models 的键是模型 ID；最外层 model 使用 提供商ID/模型ID 格式。

如果你确认所选模型要求 Responses API，不要直接照搬 Chat Completions 适配器。OpenCode 官方文档要求这类模型使用对应的 OpenAI 适配器；同时先核对 AruHub 当前接口文档与模型能力。

7. 填写 API Key

保存配置文件后，在项目文件夹打开终端并运行：

opencode

进入 OpenCode 后，在输入区运行：

/connect

1. 在提供商列表中向下找到并选择 Other。
2. Provider ID 输入 aruhub，必须与配置文件中的 aruhub 完全一致。
3. API Key 输入你在 AruHub 创建的真实密钥，然后确认。
4. OpenCode 会单独保存凭证；不要把真实 Key 写进可提交到 GitHub 的 opencode.json。

需要检查凭证是否已加载时，退出 OpenCode，在终端运行：

opencode auth list

列表中出现 aruhub 即表示凭证条目存在。不要打开或分享凭证存储文件的完整内容。

8. 填写或选择模型

先从 AruHub 模型价格页、客户端加载结果或 /v1/models 返回结果复制准确模型 ID。不要使用页面展示名称猜测模型 ID。

把配置示例中两处 replace-with-model-id 都替换为同一个准确 ID：

1. provider.aruhub.models 下的键。
2. 最外层 model 中 aruhub/ 后面的部分。

保存文件后重新启动 OpenCode，在输入区运行：

/models

选择 AruHub 下刚配置的模型。模型列表中显示该条目，说明配置文件已被读取；这还不等于接口调用已经成功。

9. 保存配置

1. 在文本编辑器中保存 opencode.json。
2. 确认文件扩展名不是 .txt。
3. 确认英文双引号、花括号和逗号成对，末尾没有多余逗号。
4. 完全退出当前 OpenCode，再在项目目录重新运行 opencode。
5. 运行 /models，确认 AruHub 和模型 ID 出现。

如果项目目录也存在 opencode.json，它可能覆盖全局设置。配置不生效时要同时检查这两个位置。

10. 发起第一次测试

新建一个空测试文件夹，在该文件夹打开终端并运行：

opencode

进入后先确认当前模型，然后输入一个低风险任务：

请只说明当前文件夹里有哪些文件，不要创建、修改或删除任何内容。

如果 OpenCode 请求读取文件，确认范围仅是测试文件夹后再批准。第一次测试不要让它部署项目、删除文件或操作数据库。

11. 如何确认配置成功

同时满足以下现象，可以认为基本配置成功：

1. /models 中选中的是 aruhub/你的模型ID。
2. 测试任务收到模型回复，而不是 401、404 或模型不存在错误。
3. AruHub 的用量记录中出现相近时间、相同模型的请求。
4. 终端没有提示配置文件解析失败。

切换模型时运行 /models 并重新选择。若需要固定默认模型，修改 opencode.json 顶层 model 字段后保存并重启。

12. 常见问题

找不到自定义提供商

先运行 /connect 并选择 Other，Provider ID 必须填写 aruhub。再检查配置文件中的键也是 aruhub，最后运行 opencode auth list。

配置文件格式错误

使用支持 JSON 的编辑器检查括号、引号和逗号。不要使用中文引号。可先复制本页完整示例，再只替换模型占位符。

Base URL 重复 /v1

正确值是 https://api.aruhub.com/v1。发现 /v1/v1 时删除多余的一段；不要填 https://api.aruhub.com/v1/chat/completions。

401

通常表示 API Key 无效、复制不完整或 aruhub 凭证没有加载。重新运行 /connect，不要在聊天或截图中展示完整 Key。

404

先检查 Base URL、模型 ID 和接口类型。Base URL 少了或多了 /v1、模型 ID 不存在、模型与所用 API 不匹配都可能导致 404。

模型列表为空

确认 models 中至少有一个模型 ID，Provider ID 与 /connect 完全一致，配置文件位于正确位置，并重新启动 OpenCode。

模型 ID 不存在

不要使用展示名称。重新从 AruHub 模型价格页、OpenCode 实际模型列表或 /v1/models 返回结果复制准确 ID。

修改配置后没有生效

完全退出并重启 OpenCode；检查当前项目是否存在另一个 opencode.json；确认修改的是正在使用的用户主目录，而不是另一个 WSL 或 Windows 用户目录。

13. 如何重置或修改配置

• 修改 Base URL 或模型：编辑 ~/.config/opencode/opencode.json，保存后重启 OpenCode。
• 更换模型：运行 /models。
• 更新凭证：再次运行 /connect，选择相同 Provider ID 后更新凭证。
• 删除旧提供商：先备份配置文件，再删除 provider 中对应的完整提供商块，同时删除指向它的顶层 model。保存并重启。
• 完全重置前，先确认项目目录没有单独的 opencode.json，避免删错配置。

14. 安全注意事项

• API Key 相当于账户密码，只保存在自己控制的设备中。
• 示例只能使用 sk-xxxxxxxx；不要把真实 Key 写进教程、截图或问题描述。
• 不要把包含 Key 的文件提交到 GitHub、同步网盘或公开聊天。
• 第一次使用不要批准删除文件、部署或数据库操作。
• 先在测试文件夹中使用只读任务，确认模型、权限和用量记录都正确。

15. 相关文档

• 快速开始
• 接口地址与密钥
• 错误排查
• 工具配置总览
• OpenAI 兼容客户端通用配置
• OpenCode 官方文档