LowHow 文档

中文

English

中文

English

深色模式

OpenCode 连接 AI 模型实战教程：配置 API Key 与测试连接 ​

📚 分类: OpenCode 入门 ⏱️ 预计耗时: 10 分钟 🎯 难度: 入门 🔧 环境要求: 已完成 OpenCode 安装并配置好网络 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

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

  • [ ] 获取主流 AI 模型（如智谱 GLM、DeepSeek）的 API Key
  • [ ] 通过两种方式（环境变量和配置文件）在 OpenCode 中配置模型
  • [ ] 测试并确认 OpenCode 与 AI 模型成功连接
  • [ ] 配置多个模型，并了解如何在它们之间切换

最终效果 ​

你将成功让 OpenCode “开口说话”。在终端输入 opencode test 后，系统将返回连接成功的确认信息，不会出现任何报错。此时，你就可以开始与 AI 助手进行对话了。

前置准备 ​

在开始前，请确认你已经完成了以下步骤：

  1. 成功安装 OpenCode：如果还未安装，请先完成 安装教程。
  2. 网络配置正确：确保你的网络环境可以访问你选择的 AI 模型 API。如果遇到问题，请参考 网络配置教程。
  3. 选择一个模型提供商：本教程将以 智谱 AI (GLM-4.7) 和 DeepSeek 为例进行演示。你可以选择其中一个，或全部尝试。

第 1 步：获取 API Key ​

🎯 目标：从 AI 模型提供商处获得一个专属的“钥匙”（API Key），用于让 OpenCode 验证你的身份。

📝 操作：

选项 A：智谱 AI (推荐，综合能力强) ​

  1. 打开浏览器，访问 智谱 AI 开放平台。
  2. 点击右上角的“注册”按钮，使用手机号或邮箱完成账号注册。
  3. 登录后，根据平台指引完成“实名认证”（通常需要提供身份证信息）。
  4. 在控制台或 API 密钥管理页面，点击“创建 API Key”。
  5. 复制生成的 API Key（它是一串类似 xxxxxxxx.xxxxxxxxxxxxxxxx 的字符串）。

⚠️ 请务必妥善保管，不要泄露给他人。

选项 B：DeepSeek (性价比高) ​

  1. 打开浏览器，访问 DeepSeek 开放平台。
  2. 注册并登录你的账号。
  3. 在控制台的 API Keys 页面，点击“创建 API Key”。
  4. 复制生成的 API Key。

✅ 验证：你手中应该已经拿到了一个以 sk- 开头的（智谱）或类似格式的 API Key 字符串。

第 2 步：配置 API Key ​

🎯 目标：将上一步获取的“钥匙”告诉 OpenCode，让它知道该用哪个模型和账户。

📝 操作：

你可以选择以下两种方式之一来配置。推荐使用“方式一：环境变量”，因为它更安全，不易误操作。

方式一：环境变量（推荐） ​

打开你的终端，执行以下命令（将 "your-api-key-here" 替换为你实际复制的 API Key）：

bash
# 如果你选择智谱模型
$ export ZHIPU_API_KEY="your-api-key-here"    // 设置智谱 AI 的 API Key

# 如果你选择 DeepSeek 模型
$ export DEEPSEEK_API_KEY="your-api-key-here"  // 设置 DeepSeek 的 API Key

💡 提示：这种方式仅在当前终端会话中有效。关闭终端后需要重新设置。为了永久生效，可以将上述命令添加到你的 shell 配置文件（如 ~/.bashrc, ~/.zshrc）中。

方式二：配置文件 ​

  1. 编辑 OpenCode 的配置文件 ~/.config/opencode/config.yaml。

  2. 将以下内容复制到文件中，并修改 api_key 的值。

yaml
# ~/.config/opencode/config.yaml
providers:
  zhipu:             # 提供商名称：智谱
    enabled: true    # 启用该提供商
    api_key: "your-api-key-here"   # 你的智谱 API Key
    model: "glm-4.7" # 模型名称
  deepseek:          # 提供商名称：DeepSeek
    enabled: true
    api_key: "your-api-key-here"   # 你的 DeepSeek API Key
    model: "deepseek-v2" # 模型名称

🤔 为什么要这样配置？providers 是一个列表，每个元素代表一个 AI 模型提供商。enabled: true 表示激活这个提供商。api_key 是你的身份凭证，model 则指定了具体使用该提供商的哪个模型。

✅ 验证：

  • 环境变量方式：在终端输入 echo $ZHIPU_API_KEY，如果能看到你设置的 API Key 字符串，说明配置成功。
  • 配置文件方式：重新打开配置文件，确认内容与你输入的一致。

第 3 步：测试连接 ​

🎯 目标：验证 OpenCode 是否能成功使用你配置的 API Key 连接到 AI 模型。

📝 操作：

在终端中执行以下命令：

bash
$ opencode test

✅ 验证： 如果一切顺利，终端将不会输出任何错误信息。这表示连接成功。

💡 提示：如果命令执行后没有任何输出，或者输出了类似 Connection successful. 的提示，也代表成功。

⚠️ 常见错误：

  • 错误 1：Error: authentication failed

    • 原因：API Key 错误或未正确设置。
    • 解决：检查你设置的 API Key 是否完整无误，并确认是通过环境变量还是配置文件设置的，确保方法正确。

  • 错误 2：Error: connection timeout

    • 原因：网络无法访问模型 API。
    • 解决：请检查你的网络连接，并参考 网络配置教程 确保可以正常访问外部 API。如果使用了代理，请确保代理配置正确。

进阶技巧：多模型配置与切换 ​

掌握基础后，你可以配置多个模型，并根据需要随时切换。

配置多个模型 ​

在 ~/.config/opencode/config.yaml 文件中，你可以像下面这样配置多个模型，并设置一个默认模型：

yaml
# ~/.config/opencode/config.yaml
providers:
  zhipu:
    enabled: true
    default: true    # 新增：将此模型设为默认
    api_key: "your-zhipu-key"
    model: "glm-4.7"
  deepseek:
    enabled: true
    api_key: "your-deepseek-key"
    model: "deepseek-v2"
  claude:
    enabled: false   # 暂时禁用 Claude 模型
    api_key: "your-claude-key"
    model: "claude-3-opus-20240229"

在对话中切换模型 ​

在 OpenCode 的聊天界面中，输入以下命令可以实时切换当前使用的模型：

bash
/model deepseek

这会将会话模型切换到你配置的 deepseek 提供商。

常见问题 (FAQ) ​

Q1: 我没有 API Key，可以体验 OpenCode 吗？A: 可以！OpenCode 提供了一个名为 OpenCode Zen 的免费模型，无需 API Key，完全免费。你可以在 免费模型 (OpenCode Zen) 页面了解更多。

Q2: 配置了多个模型，如何知道当前正在使用哪个？A: 你可以查看 OpenCode 界面上的模型指示器，或者在聊天中输入 /model 命令查看当前模型。

Q3: 我想换一个模型，需要重新配置吗？A: 不需要。只要你在配置文件中添加了该模型，就可以通过 /model 命令随时切换。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 获取 API Key：你学会了如何从智谱 AI 或 DeepSeek 获取 API Key。
  2. 配置 API Key：你掌握了通过“环境变量”和“配置文件”两种方式配置 API Key。
  3. 测试连接：你学会了使用 opencode test 命令来验证连接是否成功。
  4. 多模型管理：你了解了如何配置多个模型并使用 /model 命令切换。

© 2026 LowHow