文档中心DOCS

Open Code 接入教程

下载 OpenCode，并通过 OpenAI 兼容 Provider 接入 服务平台

≡ ON THIS PAGE
适合什么场景一、准备 服务平台 参数二、下载和安装 OpenCode三、按系统选择配置方式四、添加 服务平台 Provider五、CLI 配置文件示例六、验证是否可用七、推荐的第一次任务八、常见问题参考入口

适合什么场景

Open Code 适合喜欢终端开发、希望用开源编码智能体处理项目任务的用户。它可以用于代码解释、文件修改、测试运行、报错排查和开发计划拆解。

终端开发

在项目目录里启动 OpenCode，连续处理代码任务。

自定义 Provider

通过 OpenAI Compatible 接入 服务平台 Base URL 和模型。

低风险验证

先让它只读项目，再逐步进入真实修改。

服务器场景

CLI 配置更适合 WSL、Linux、远程终端和容器。

一、准备 服务平台 参数

Provider

OpenAI Compatible、自定义 OpenAI 或类似选项。

Base URL

https://your-api-host.example

API Key

服务平台 控制台创建的真实密钥。

Model

以 服务平台 当前可用模型为准，示例使用 gpt-5.4。

二、下载和安装 OpenCode

1
打开 OpenCode 下载页。
2
根据自己的系统选择桌面版或终端版本。
3
安装完成后先启动一次 OpenCode，确认软件能正常打开。
4
如果使用终端版本，进入一个普通项目目录再启动，方便验证它能否读取项目文件。

三、按系统选择配置方式

桌面用户优先在设置页填写 Provider、Base URL、API Key 和 Model。

CLI 用户可以先在 PowerShell 临时设置密钥：

$env:CUSTOM_API_KEY="your_api_key_here"
opencode

如果项目在 WSL 中运行，请在 WSL 内按 Linux 方式重新配置。

桌面用户优先在设置页填写 Provider、Base URL、API Key 和 Model。

CLI 用户可以在 zsh/bash 中临时设置密钥：

export CUSTOM_API_KEY="your_api_key_here"
opencode

全局配置通常放在 ~/.config/opencode/opencode.json。

推荐用环境变量加 opencode.json，便于服务器、容器和远程终端复用。

export CUSTOM_API_KEY="your_api_key_here"
opencode

全局配置通常在 ~/.config/opencode/opencode.json，项目配置可以放在项目根目录 opencode.json。

四、添加 服务平台 Provider

1
进入 OpenCode 设置页，找到 Settings、Provider、Models 或类似菜单。
2
选择 Add Provider、Custom Provider 或 OpenAI Compatible。
3
服务商名称填写 服务平台。
4
Base URL 填写 https://your-api-host.example。
5
API Key 填写 服务平台 控制台创建的密钥。
6
Model 填写 服务平台 可用模型，例如 gpt-5.4，然后保存。
图片加载中...
在设置页找到 Provider 或模型服务入口。
图片加载中...
填写 Base URL、API Key 和模型名称后保存。

五、CLI 配置文件示例

如果使用 OpenCode CLI / TUI，可以在项目根目录创建 opencode.json，或者在全局配置中添加 服务平台 provider。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "custom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "服务平台",
      "options": {
        "baseURL": "https://your-api-host.example",
        "apiKey": "{env:CUSTOM_API_KEY}"
      },
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4"
        }
      }
    }
  },
  "model": "custom/gpt-5.4"
}

项目配置

放在项目根目录 opencode.json，只影响当前项目。

全局配置

放在 ~/.config/opencode/opencode.json，适合所有项目共用。

六、验证是否可用

配置完成后，重启 OpenCode，并输入一个简单任务：

请阅读当前项目，只总结目录结构，不要修改任何文件。
图片加载中...
第一次测试建议只让它阅读项目，不执行修改。
图片加载中...
能稳定返回内容后，再进入真实开发任务。

认证通过

没有出现 API Key 认证失败提示。

模型可用

没有出现模型不存在或模型不可用提示。

网络正常

没有明显连接失败或超时错误。

能读项目

能正常收到模型返回的项目分析内容。

七、推荐的第一次任务

请解释这个项目的主要目录和入口文件。

请找出 package.json 里的启动命令，并告诉我本地应该怎么运行。

请审查当前改动，只列出可能的问题，不要修改文件。

八、常见问题

Q.找不到 Base URL 输入框

优先找 Endpoint、API Host、Base URL、Custom URL、OpenAI Compatible 这些关键词。如果当前版本完全不能修改接口地址，就无法直接接入 服务平台，建议更新 OpenCode 或换用 Codex。

Q.提示 API Key 无效

检查 API Key 是否来自 服务平台 控制台，是否复制了多余空格或换行，是否填错到了模型名称或组织 ID 字段里，以及当前 服务平台 账号是否仍有额度。

Q.提示模型不存在

把模型名称改成 服务平台 当前可用模型。不要使用其他平台文档里的模型名。

Q.提示网络超时

确认 Base URL 是 https://your-api-host.example。如果仍然超时，再检查本机网络、代理和防火墙。

参考入口