Open Code 文档

主题

首页文档搜索

OpenCode 基础配置实战教程 ​

📚 分类: AI编程助手 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode

你将学到什么 ​

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

  • [ ] 找到并理解 OpenCode 配置文件 (opencode.json) 的结构
  • [ ] 根据自身需求，配置 API 连接（以智谱 GLM-4.7 为例）
  • [ ] 调整编辑器界面主题、字体等视觉风格
  • [ ] 自定义快捷键，提升操作效率

最终效果 ​

你将成功定制 OpenCode，使其连接到您选择的 AI 模型，并以你喜欢的界面风格和快捷键运行。例如，你将能按下 Ctrl+Shift+N 快速创建一个新的对话窗口。

前置准备 ​

在开始前，请确保你已满足以下条件：

检查项说明验证方法
OpenCode 已安装已完成安装流程在终端输入 opencode --version，应输出版本号
文本编辑器用于编辑配置文件如 VS Code, Sublime Text, Vim 等
API 密钥对应 AI 模型提供商的密钥已从服务商处获取（如智谱、OpenAI 等）

1. 了解配置文件位置 ​

OpenCode 的核心配置存储在一个名为 opencode.json 的文件中。它的位置因操作系统而异：

操作系统配置文件路径
macOS / Linux~/.opencode/opencode.json
Windows%USERPROFILE%\.opencode\opencode.json

💡 提示: 你可以直接在终端中使用以下命令快速打开并编辑配置文件：

bash
$ opencode config edit

✅ 验证: 执行上述命令后，你的文本编辑器应该会打开一个 .json 文件。

第 1 步：配置 API 连接（以智谱 GLM-4.7 为例） ​

🎯 目标：让 OpenCode 能够通过 API 连接到智谱 AI 的 GLM-4.7 模型。

🤔 为什么要这样做？ OpenCode 本身不包含 AI 模型，它需要连接到外部的模型提供商（如智谱、OpenAI）才能工作。这一步就是告诉 OpenCode “你是谁”和“你要用哪个模型”。

📝 操作：

  1. 使用 opencode config edit 命令打开 opencode.json 文件。

  2. 找到或创建 "api" 这个配置项。如果文件是空的，你需要添加整个配置结构。将以下代码复制到文件中：

json
{
  "api": {
    "provider": "zhipu",          // 指定模型提供商为"智谱"
    "model": "glm-4.7",           // 指定要使用的模型
    "apiKey": "your-zhipu-api-key", // 替换为你的真实API密钥
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4", // 智谱的API地址
    "timeout": 60000,             // 请求超时时间（毫秒）
    "maxTokens": 16384            // 模型最大输出Token数
  }
}

⚠️ 注意：

  • 请务必将 "your-zhipu-api-key" 替换成你从智谱 AI 官网获取的真实 API 密钥。
  • apiKey 是敏感信息，不要分享给他人。更安全的做法是使用环境变量，例如："apiKey": "${ZHIPU_API_KEY}"。
  1. 保存文件。

✅ 验证：

  1. 重启 OpenCode（关闭所有 OpenCode 窗口，然后重新启动）。
  2. 在 OpenCode 的对话框中输入以下内容并发送：
    你好，请介绍一下你自己
  3. 预期结果：AI 会回复一段自我介绍，并且回复内容是基于 GLM-4.7 模型的，说明配置成功。

第 2 步：调整界面设置（主题、字体） ​

🎯 目标：自定义编辑器的外观，使其更符合你的审美和工作习惯。

📝 操作：

  1. 再次使用 opencode config edit 打开配置文件。

  2. 找到或创建 "ui" 这个配置项。修改或添加以下配置：

json
{
  "ui": {
    "theme": "dark",              // 可选: "dark", "light", "system"
    "language": "zh-CN",          // 界面语言
    "fontSize": 16,               // 编辑区字体大小
    "fontFamily": "JetBrains Mono", // 编辑区字体
    "tabSize": 2,                 // Tab键宽度
    "wordWrap": true,             // 自动换行
    "minimap": false              // 是否显示代码缩略图
  }
}

💡 提示：

  • theme 设置为 "system" 会自动跟随你的操作系统主题。
  • fontFamily 可以设置为任何你系统上已安装的等宽字体，例如 "Fira Code"。
  1. 保存文件。

✅ 验证：

  1. 重启 OpenCode。
  2. 观察界面变化：
    • 编辑器背景和菜单应该变为深色（如果选择了 dark 主题）。
    • 代码字体应该变大，并且变为你指定的字体。

第 3 步：配置常用快捷键 ​

🎯 目标：为常用的操作（如打开终端、新建会话）设置你习惯的键盘快捷键，提升操作流畅度。

📝 操作：

  1. 使用 opencode config edit 打开配置文件。

  2. 找到或创建 "keybindings" 这个配置项。复制并修改以下示例：

json
{
  "keybindings": {
    "toggleTerminal": "ctrl+`",       // 切换终端面板
    "newSession": "ctrl+shift+n",     // 新建一个AI对话会话
    "runCode": "ctrl+enter",          // 执行当前代码块
    "formatCode": "ctrl+shift+f"      // 格式化代码
  }
}

⚠️ 常见错误：

  • 快捷键冲突：你设置的快捷键可能与操作系统或其他软件的快捷键冲突。例如，Ctrl+C 在终端中是复制，但在 OpenCode 中可能会被覆盖。
  • 解决方法：如果快捷键无效，尝试更换一个不常用的组合，如 Ctrl+Alt+K。
  1. 保存文件。

✅ 验证：

  1. 重启 OpenCode。
  2. 测试快捷键：
    • 按下 Ctrl+Shift+N，应该会创建一个新的 AI 对话标签页。
    • 按下 `Ctrl+``，应该会打开或关闭底部的终端面板。

进阶技巧：使用环境变量管理 API 密钥 ​

🎯 目标：避免将 API 密钥明文写在配置文件中，提高安全性。

📝 操作：

  1. 在你的系统环境变量中设置一个变量，例如 ZHIPU_API_KEY，其值为你的智谱 API 密钥。

    • macOS/Linux: 在 ~/.bashrc 或 ~/.zshrc 中添加 export ZHIPU_API_KEY="your-key"，然后执行 source ~/.zshrc。
    • Windows: 在“系统属性” -> “高级” -> “环境变量”中添加。

  2. 修改 opencode.json 中的 apiKey 配置：

json
// "apiKey": "your-zhipu-api-key",
// "apiKey": "${ZHIPU_API_KEY}",
  1. 保存文件并重启 OpenCode。

✅ 验证：功能与第 1 步验证相同。即使别人看到了你的 opencode.json 文件，也无法获取你的真实 API 密钥。

常见问题 (FAQ) ​

Q1: 修改配置后，为什么没有任何变化？A: 最常见的原因是配置文件格式错误。JSON 格式非常严格，比如多了一个逗号、引号不配对都会导致整个文件失效。

  • 解决方法：使用在线 JSON 验证工具（如 jsonlint.com）检查你的 opencode.json 文件。确保所有键名和字符串值都被双引号 " 包裹。

Q2: 报错 API connection failed 或 401 Unauthorized，怎么办？A: 这通常表示 API 密钥错误或网络问题。

  • 检查点：
    1. apiKey 是否填写正确，没有多余的空格或字符。
    2. 你的 API 密钥是否还有效、余额是否充足。
    3. 如果你使用了环境变量，确保变量名和配置文件中的 ${} 引用完全一致。

Q3: 我想用 OpenAI 的 GPT-4，该怎么配置？A: 修改 api 配置项中的 provider 和 model 即可。

json
{
  "api": {
    "provider": "openai",
    "model": "gpt-4-turbo",
    "apiKey": "${OPENAI_API_KEY}",
    "baseUrl": "https://api.openai.com/v1" // 可选，如果你使用中转API则修改此项
  }
}

总结 ​

恭喜你完成了本教程！🎉

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

  1. 配置文件位置：~/.opencode/opencode.json，可以通过 opencode config edit 快速编辑。
  2. API 配置：通过 api 字段连接你选择的 AI 模型，并强烈建议使用环境变量管理密钥。
  3. 界面定制：通过 ui 字段修改主题、字体、字号等视觉元素。
  4. 快捷键配置：通过 keybindings 字段自定义常用操作，提升工作效率。

下一步 ​

如果你想继续深入，建议学习：

  • 📖 [OpenCode 进阶配置教程]：学习更多高级配置，如文件排除、终端配置、扩展管理等。
  • 📖 [OpenCode 场景实战]：了解如何将 OpenCode 应用到具体的编程、写作等任务中。

💡 练习任务：尝试在配置文件中添加 "files" 配置项，将 node_modules 和 dist 文件夹排除在 AI 的上下文之外，看看效果如何。

yaml

Open Code 文档社区

© 2026 Open Code. All rights reserved.