LowHow 文档

中文

English

中文

English

深色模式

OpenCode 网络配置实战指南：国内用户快速连接 AI 模型的三种方法 ​

📚 分类: OpenCode 入门配置 ⏱️ 预计耗时: 10 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode (版本不限，以最新稳定版为准)

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 判断你的网络环境，并为 OpenCode 选择合适的网络配置方案
  • [ ] 掌握三种配置方法：使用国产模型、配置系统代理、使用模型中转服务
  • [ ] 独立完成配置，并使用 opencode doctor 命令验证网络连接是否成功
  • [ ] 解决常见的网络连接问题，如代理失效或模型连接失败

最终效果 ​

成功运行 opencode doctor 命令后，你将看到终端输出一份诊断报告，其中网络连通性、代理设置和模型连接状态均为绿色通过（✅ 或 OK），这意味着 OpenCode 已准备就绪，可以连接各种 AI 模型。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode最新稳定版opencode --version

1. 打开终端 ​

  • macOS / Linux: 打开“终端”(Terminal) 应用。
  • Windows: 打开“PowerShell”或“命令提示符”(Command Prompt)。

2. 确认 OpenCode 已安装 ​

在终端中输入以下命令并回车：

bash
$ opencode --version    // 检查 OpenCode 版本

✅ 验证：如果终端返回一个版本号（例如 v1.2.3），说明安装成功。

第 1 步：评估你的网络环境 ​

🎯 目标：判断你的网络是否可以直接访问你需要的 AI 模型服务，从而决定采用哪种配置方案。

📝 操作： 首先，你需要决定要使用哪个 AI 模型。这决定了你需要采用哪种网络配置方案。

  • 如果你想用国产模型（如智谱 GLM-4.7, DeepSeek, 通义千问）：恭喜你，你不需要进行任何特殊网络配置！请直接跳到 第 3 步：测试网络连接 进行验证。
  • 如果你想用海外模型（如 OpenAI GPT, Claude）：你需要配置代理或使用模型中转服务。请继续到 第 2 步：配置网络连接。

🤔 为什么要这样做？ 由于网络限制，国内用户直接连接 OpenAI、Claude 等海外服务商可能会遇到连接超时或完全无法连接的问题。而国产模型服务商在国内有服务器，可以直接访问。

第 2 步：配置网络连接 ​

🎯 目标：为 OpenCode 设置代理或中转服务，使其能够连接到海外 AI 模型。

注意：如果你已经决定使用国产模型，请跳过此步骤。

方案一：配置系统代理（推荐） ​

这是最常用的方法，让 OpenCode 使用你电脑上已有的代理软件（如 Clash, V2Ray）。

📝 操作：

  1. 确保代理软件已开启：请先确认你的代理软件正在运行，并记下它的代理地址和端口号。通常是 127.0.0.1:7890（具体以你的软件设置为准）。

  2. 设置环境变量：在终端中执行以下命令。你需要将 127.0.0.1:7890 替换为你自己的代理地址和端口。

    Linux / macOS:

    bash
    $ export HTTP_PROXY="http://127.0.0.1:7890"    // 设置 HTTP 代理
$ export HTTPS_PROXY="http://127.0.0.1:7890"   // 设置 HTTPS 代理

    Windows (PowerShell):

    powershell
    $env:HTTP_PROXY = "http://127.0.0.1:7890"      // 设置 HTTP 代理
$env:HTTPS_PROXY = "http://127.0.0.1:7890"     // 设置 HTTPS 代理

    💡 提示：这种设置是临时的，只对当前终端窗口有效。关闭终端后需要重新设置。

✅ 验证：设置后，你可以直接进行 第 3 步：测试网络连接 来验证代理是否生效。

方案二：在 OpenCode 配置文件中设置（推荐） ​

这种方法更持久，设置一次后永久生效。

📝 操作：

  1. 打开配置文件：使用文本编辑器（如 VS Code, Vim）打开 OpenCode 的配置文件 ~/.config/opencode/config.yaml。

    bash
    $ code ~/.config/opencode/config.yaml    // 使用 VS Code 打开

  2. 添加代理配置：在文件中找到 network: 部分，如果没有就自己添加。将 127.0.0.1:7890 替换为你自己的代理地址和端口。

    yaml
    // ~/.config/opencode/config.yaml
network:
  proxy:
    enabled: true           // [!code ++] 启用代理
    http: "http://127.0.0.1:7890"   // HTTP 代理地址
    https: "http://127.0.0.1:7890"  // HTTPS 代理地址

    ⚠️ 注意：请确保 enabled 设置为 true，否则配置不生效。

✅ 验证：保存配置文件后，配置即生效。无需重启 OpenCode。直接进行 第 3 步：测试网络连接 来验证。

方案三：使用模型中转服务 ​

如果你没有自己的代理，可以使用一些提供中转服务的平台来连接海外模型。

📝 操作：

  1. 获取中转服务地址：你需要从第三方服务商（如某些云服务或社区提供的 API 代理）获取一个中转服务地址（endpoint），例如 https://api.claude-code.com。

  2. 修改配置文件：同样打开 ~/.config/opencode/config.yaml，找到你想使用的模型提供商（例如 claude），并添加 relay 配置。

    yaml
    // ~/.config/opencode/config.yaml
providers:
  claude:
    enabled: true
    relay:
      enabled: true          // [!code ++] 启用中转
      endpoint: "https://api.claude-code.com" // 你的中转服务地址

✅ 验证：保存配置文件后，配置即生效。直接进行 第 3 步：测试网络连接 来验证。

第 3 步：测试网络连接 ​

🎯 目标：验证你的网络配置是否正确，OpenCode 能否成功连接到 AI 模型。

📝 操作： 在终端中运行 OpenCode 的诊断命令：

bash
$ opencode doctor    // 运行网络诊断

✅ 验证： 执行后，终端将输出详细的诊断报告，包括：

  • 网络连通性：检查你的电脑能否访问外网。
  • 代理设置：检查 OpenCode 是否成功读取了你的代理配置。
  • 模型连接：检查 OpenCode 能否成功连接到你配置的 AI 模型。

如果所有检查项都显示 ✅ 或 OK，则说明网络配置成功！

🤔 为什么要测试？opencode doctor 是一个强大的排错工具，它能帮你快速定位问题是出在网络、代理还是模型本身。

⚠️ 常见错误及解决：

  • 问题：运行 opencode doctor 后，显示网络连接失败。 解决：检查你的代理软件是否开启，地址和端口是否填写正确。尝试更换代理软件或端口。

  • 问题：代理设置正确，但模型连接失败。 解决：

    1. 检查你的模型 API Key 是否有效且已配置。
    2. 检查模型服务商是否处于正常运行状态。
    3. 如果你使用了中转服务，请确认中转地址是否正确且服务可用。

进阶技巧（可选） ​

永久设置环境变量 ​

如果你使用方案一（环境变量），可以将 export 命令添加到你的 shell 配置文件中（如 ~/.bashrc, ~/.zshrc），这样每次打开终端都会自动生效。

bash
// 在 ~/.bashrc 或 ~/.zshrc 文件末尾添加
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

常见问题 (FAQ) ​

Q1: 我该选择哪个国产模型？A: 推荐首选 智谱 GLM-4.7，它在性能和价格之间取得了很好的平衡。如果你追求性价比，DeepSeek 也是一个不错的选择。

Q2: 使用代理后还是连不上，怎么办？A:

  1. 检查代理软件是否正常运行，端口是否正确（例如 7890）。
  2. 尝试在浏览器中访问 http://google.com，检查代理是否对浏览器生效。如果浏览器也无法访问，说明是代理软件本身的问题。
  3. 尝试更换代理端口或更换一个代理软件。

Q3: 如何判断我的 OpenCode 是否正在使用代理？A: 运行 opencode doctor，查看“代理设置”部分的检查结果。它会明确显示是否检测到代理配置。

总结 ​

恭喜你完成了 OpenCode 的网络配置！🎉

回顾一下我们今天学到的核心内容：

  1. 网络环境评估：根据你想使用的模型（国产或海外）选择合适的配置方案。
  2. 三种配置方案：学会了使用国产模型（无需配置）、设置系统代理（临时或永久）、使用模型中转服务。
  3. 验证与排错：掌握了使用 opencode doctor 命令测试网络连接并解决常见问题。

© 2026 LowHow