OpenCode 配置文件 opencode.json 实战教程

📚 分类: OpenCode 进阶配置 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode（版本 ≥ 1.0）、文本编辑器（如 VS Code）

---

你将学到什么

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

• [ ] 找到并理解 OpenCode 的核心配置文件 opencode.json 的位置与结构
• [ ] 配置 API 连接，让 OpenCode 成功连接到智谱 GLM-4.7 等 AI 模型
• [ ] 个性化界面，调整主题、字体、字号等 UI 设置
• [ ] 自定义快捷键，提升日常操作效率
• [ ] 设置文件排除与自动保存等进阶功能

最终效果

你将获得一个完全按照自己喜好定制的 OpenCode 编辑器，其界面风格、字体、快捷键都符合你的个人习惯，并且成功连接到你选择的 AI 模型（本教程以智谱 GLM-4.7 为例）。

---

前置准备

在开始前，请确认你的环境满足以下条件。请逐一检查并完成。

检查项	要求	验证命令
OpenCode 已安装	版本 ≥ 1.0	opencode --version
文本编辑器	任意（如 VS Code）	能打开 .json 文件即可
智谱 API 密钥	已从智谱开放平台申请	登录平台查看

1. 确认 OpenCode 安装成功

首先，打开你的终端（Terminal），输入以下命令进行验证。

$ opencode --version    // 查看 OpenCode 版本

✅ 验证：如果终端输出了类似 1.2.3 的版本号，说明安装成功。

💡 提示：如果提示 command not found，请先参考 OpenCode 安装教程完成安装。

2. 了解 AGENTS.md 文件（必修）

AGENTS.md 是 OpenCode 的 AI 助手行为配置文件。虽然本教程不深入讲解，但建议你先阅读相关文档了解其作用。简单来说，它决定了 AI 助手如何理解你的项目。

---

第 1 步：找到并打开配置文件

🎯 目标：找到 OpenCode 的配置文件 opencode.json，并了解它在不同操作系统上的存放位置。

📝 操作：

OpenCode 的配置文件位于用户主目录下的 .opencode 文件夹中。具体路径如下：

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

你可以通过 OpenCode 内置命令快速打开并编辑它：

# macOS / Linux
$ opencode config edit    // 用 OpenCode 内置命令编辑配置

或者，你也可以手动找到并打开它：

# 以 macOS 为例，手动进入目录
$ cd ~/.opencode
$ ls -la                   // 列出当前目录下所有文件，确认 opencode.json 是否存在

✅ 验证： 执行 ls -la ~/.opencode 后，你应该能在输出中看到类似下面的文件列表，其中包含 opencode.json。

drwxr-xr-x   ... .opencode/
-rw-r--r--   ... opencode.json

💡 提示：如果文件不存在，不用担心。OpenCode 会在你第一次启动或执行 opencode config edit 命令时，自动创建一个包含默认配置的 opencode.json 文件。

---

第 2 步：理解配置文件结构

🎯 目标：了解 opencode.json 的基本结构，知道每个配置区块的作用，为后续修改打下基础。

📝 操作：

用你的文本编辑器打开 opencode.json 文件。你会看到类似下面的结构（如果文件是新建的，内容可能更少，但结构类似）：

{
  "$schema": "https://opencode.ai/schema.json",   // 配置文件格式定义，用于编辑器智能提示
  "version": "1.0",                                 // 配置文件版本号
  "api": {                                           // API 连接配置
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "your-api-key"
  },
  "ui": {                                            // 界面设置
    "theme": "dark",
    "language": "zh-CN",
    "fontSize": 14
  },
  "features": {                                      // 功能开关
    "autoComplete": true,
    "syntaxHighlight": true,
    "lineNumbers": true
  }
}

🤔 为什么要这样做？ 配置文件采用 JSON 格式，通过不同的“区块”来管理不同类型的设置。这样做的优点是结构清晰、易于维护。

• api：控制 AI 模型连接，决定使用哪个模型、API 密钥等。
• ui：控制界面外观，如主题、字体、语言。
• features：控制编辑器功能，如自动补全、语法高亮。
• keybindings：自定义快捷键。
• files：文件管理设置，如排除某些文件。

✅ 验证：确认文件内容是一个有效的 JSON 格式。一个简单的检查方法是：确保所有括号 {}、[] 都正确配对，且最后一个键值对后面没有多余的逗号 ,。

⚠️ 常见错误： 这是初学者最容易犯错的地方。例如，在最后一个属性 lineNumbers 后面多写了一个逗号 ,：

"lineNumbers": true,   // 错误：末尾多了一个逗号
"lineNumbers": true    // 正确：最后一个属性后面不能有逗号

解决方法：使用在线 JSON 验证工具（如 jsonlint.com）粘贴你的配置内容进行校验。

---

第 3 步：配置 API 连接（连接智谱 GLM-4.7）

🎯 目标：配置 OpenCode 使用智谱 GLM-4.7 模型，让 AI 助手能正常对话。

📝 操作：

在 opencode.json 中，找到 api 区块（如果不存在，就自己添加）。将其修改为如下内容：

{
  "api": {
    "provider": "zhipu",          // 模型提供商：zhipu / deepseek / openai 等
    "model": "glm-4.7",           // 模型名称：glm-4.7 / gpt-4 / deepseek-chat 等
    "apiKey": "your-zhipu-api-key", // 你的智谱 API 密钥（请替换为真实密钥）
    "apiKey": "${ZHIPU_API_KEY}",  // 推荐：从环境变量读取，更安全
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4", // API 地址（可选，不填则使用默认）
    "timeout": 60000,              // 超时时间（毫秒），默认 60000
    "maxTokens": 16384             // 单次回答最大 Token 数，默认 16384
  }
}

重要：强烈建议不要将 API 密钥直接写在配置文件中！请使用环境变量方式。

1. 如上所示，将 apiKey 的值设置为 ${ZHIPU_API_KEY}。
2. 在你的终端中设置环境变量：

   # macOS / Linux
   $ export ZHIPU_API_KEY="你的真实智谱API密钥"
   
   # 如果你希望每次打开终端都自动生效，可以把它添加到 ~/.zshrc 或 ~/.bashrc 文件中
   $ echo 'export ZHIPU_API_KEY="你的真实智谱API密钥"' >> ~/.zshrc

✅ 验证：

保存配置文件，然后重启 OpenCode。在对话输入框中输入以下内容并发送：

你好，请介绍一下你自己

如果配置成功，你应该会看到 AI 使用智谱模型进行回复，例如：

你好！我是基于智谱 GLM-4.7 的 AI 助手，很高兴为你服务...

⚠️ 常见错误：

• API 连接失败：检查 API 密钥是否正确、是否过期。登录智谱开放平台确认。
• 超时错误：检查你的网络连接是否正常。如果网络较慢，可以尝试增大 timeout 的值，例如 120000（120秒）。
• 模型名称错误：确认 model 字段的值（如 glm-4.7）与智谱平台提供的模型名称完全一致。

---

第 4 步：调整界面设置

🎯 目标：修改主题、字体、字号等界面设置，让编辑器更符合你的视觉偏好。

📝 操作：

在 opencode.json 中找到或添加 ui 区块，并修改为你喜欢的值：

{
  "ui": {
    "theme": "dark",              // 主题：dark（暗色）/ light（亮色）/ system（跟随系统）
    "language": "zh-CN",          // 界面语言：zh-CN（简体中文）/ en-US（英文）
    "fontSize": 16,               // 字体大小（像素）
    "fontFamily": "JetBrains Mono", // 字体名称（需系统已安装）
    "tabSize": 2,                 // Tab 键缩进的空格数
    "wordWrap": true,             // 自动换行：true / false
    "minimap": false              // 显示代码小地图：true / false
  }
}

✅ 验证：

保存配置文件并重启 OpenCode。你应该能看到：

• 界面主题变为暗色（如果设置了 "theme": "dark"）。
• 代码编辑区的字体变大（如果设置了 "fontSize": 16）。
• 如果设置了 "fontFamily": "JetBrains Mono" 且系统已安装该字体，字体样式会随之改变。

💡 提示：fontFamily 需要系统中已安装该字体。如果不确定，可以留空此字段，OpenCode 会使用系统默认的等宽字体。

---

第 5 步：配置常用功能开关

🎯 目标：控制编辑器的功能开关，如自动补全、语法高亮、保存时格式化等。

📝 操作：

在 opencode.json 中找到或添加 features 区块，并根据你的习惯进行修改：

{
  "features": {
    "autoComplete": true,               // 自动补全：true / false
    "syntaxHighlight": true,            // 语法高亮：true / false
    "lineNumbers": true,                // 显示行号：true / false
    "bracketPairColorization": true,    // 括号配对着色：true / false
    "autoClosingBrackets": "always",    // 自动闭合括号：always（总是）/ never / beforeSpace
    "autoClosingQuotes": "beforeSpace", // 自动闭合引号：always / never / beforeSpace（在空格前闭合）
    "formatOnSave": true,               // 保存时自动格式化代码：true / false
    "autoSave": "afterDelay",           // 自动保存：afterDelay（延迟后）/ onFocusChange（失焦时）/ off
    "autoSaveDelay": 1000               // 自动保存延迟（毫秒），仅当 autoSave 为 afterDelay 时生效
  }
}

✅ 验证：

• 保存配置并重启 OpenCode。
• 新建一个文件，输入 function 或 console.，观察是否出现自动补全提示。
• 修改文件后，按下 Ctrl+S（或 Cmd+S）保存，观察代码是否自动变得整齐（如果 formatOnSave 为 true）。

---

第 6 步：自定义快捷键

🎯 目标：自定义常用操作的快捷键，让操作更顺手，提高工作效率。

📝 操作：

在 opencode.json 中找到或添加 keybindings 区块：

{
  "keybindings": {
    "toggleTerminal": "ctrl+`",           // 切换终端面板的显示/隐藏
    "newSession": "ctrl+shift+n",         // 新建一个 AI 对话会话
    "runCode": "ctrl+enter",              // 运行当前选中的代码块
    "formatCode": "ctrl+shift+f",         // 格式化当前文件的代码
    "toggleSidebar": "ctrl+b",            // 切换侧边栏的显示/隐藏
    "copyCode": "ctrl+shift+c"            // 复制代码到剪贴板
  }
}

💡 提示：快捷键的格式为 修饰键+键。支持 ctrl、shift、alt、meta（Mac 的 Command 键 ⌘）等修饰键组合。例如，Mac 用户可以将 toggleTerminal 设置为 `cmd+``。

✅ 验证：

• 保存配置并重启 OpenCode。
• 按下你刚刚设置的快捷键，比如 ctrl+``（或 cmd+``），看终端面板是否成功弹出。
• 按下 ctrl+b（或 cmd+b），看侧边栏是否成功切换。

⚠️ 常见错误：

• 快捷键冲突：如果你设置的快捷键被系统或其他应用（如浏览器的快捷键）占用了，OpenCode 可能无法响应。请尝试更换一个不冲突的组合键，例如 ctrl+alt+t。
• 键位不生效：请仔细检查你的快捷键语法是否正确，例如 ctrl+ 后面不能有空格。

---

第 7 步：配置文件排除与自动刷新

🎯 目标：排除 node_modules 等无关文件，让文件列表更清爽；并开启文件自动刷新功能。

📝 操作：

在 opencode.json 中找到或添加 files 区块：

{
  "files": {
    "exclude": [                       // 排除的文件/目录列表（支持 glob 模式）
      "node_modules/**",               // 排除所有 node_modules 目录及其内容
      "dist/**",                       // 排除构建产物目录
      "build/**",                      // 排除构建产物目录
      "*.log",                         // 排除所有 .log 日志文件
      ".git/**",                       // 排除 Git 版本控制目录
      ".vscode/**"                     // 排除 VS Code 配置目录
    ],
    "watch": true,                     // 监听文件变化：true / false
    "autoRefresh": true,               // 自动刷新文件列表：true / false
    "defaultLanguage": "typescript"    // 新建文件的默认语言
  }
}

💡 提示：exclude 中使用的 ** 是 glob 模式通配符，表示“任意层级的目录”。node_modules/** 的意思是“任何名为 node_modules 的目录及其内部的所有内容”。

✅ 验证：

• 保存配置并重启 OpenCode。
• 在 OpenCode 的文件资源管理器中，你应该不会再看到 node_modules 等被你排除的目录和文件，界面变得非常干净。
• 在项目目录中新建一个文件，OpenCode 的文件列表应该会自动刷新，显示出新文件。

---

进阶技巧（可选）

掌握基础配置后，你可以尝试：

1. 配置多个 AI 模型备用

OpenCode 支持配置多个模型，方便你在对话时切换。例如：

{
  "api": {
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "${ZHIPU_API_KEY}",
    "alternatives": [                    // 备用模型列表
      {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "apiKey": "${DEEPSEEK_API_KEY}"
      },
      {
        "provider": "openai",
        "model": "gpt-4",
        "apiKey": "${OPENAI_API_KEY}"
      }
    ]
  }
}

---

常见问题 (FAQ)

Q1: 配置不生效怎么办？A: 最常见的原因是 JSON 格式错误。请使用在线 JSON 验证工具（如 jsonlint.com）检查文件格式。另外，修改配置后必须重启 OpenCode 才能生效。

Q2: API 连接失败，提示 "401 Unauthorized"？A: 这说明你的 API 密钥错误或已过期。请登录智谱开放平台重新生成一个密钥，并确保在配置文件中（或通过环境变量）正确填写。

Q3: 主题没有变化？A: 检查 theme 值是否拼写正确（例如 dark 不要写成 drak）。另外，修改主题后需要重启 OpenCode 才能完全生效。

Q4: 快捷键冲突怎么办？A: 例如，Mac 系统的 cmd+q 是“退出应用”的全局快捷键，如果你把它设置给 OpenCode，就会冲突。请更换为其他组合键，如 ctrl+alt+t。

Q5: 如何恢复默认配置？A: 直接删除 ~/.opencode/opencode.json 文件，然后重启 OpenCode。程序会自动生成一个全新的默认配置文件。

---

总结

恭喜你完成了本教程！🎉

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

1. 配置文件位置：~/.opencode/opencode.json （macOS/Linux）或 %USERPROFILE%\.opencode\opencode.json （Windows）
2. API 配置：通过 provider、model、apiKey 连接 AI 模型，推荐使用环境变量存储密钥。
3. UI 设置：通过 theme、fontSize、fontFamily 等参数定制界面外观。
4. 功能开关：通过 autoComplete、formatOnSave 等选项控制编辑器行为。
5. 快捷键：通过 keybindings 区块自定义操作快捷键，提升效率。
6. 文件管理：通过 files.exclude 排除无关文件，保持项目整洁。

---

下一步

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

• 📖 5.1b 配置进阶 - 掌握更多高级配置项和优化技巧
• 📖 5.22 调试与诊断 - 学习如何排查配置问题
• 📖 速查手册：配置选项 - 完整的配置项参考文档

💡 练习任务：尝试修改配置，将主题设置为 light，并将默认语言改为 python，然后重启验证效果。这是巩固知识的最佳方式。

## 相关文档

- [OpenCode Provider 配置完全指南：从入门到精通](/docs/pei-zhi-can-kao/opencode-provider-pei-zhi-wan-quan-zhi-nan-cong-ru-men-dao-jing-tong.html)