OpenCode 个性化配置实战教程

📚 分类: OpenCode 入门 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode 的 Windows/macOS/Linux 系统

你将学到什么

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

[ ] 找到并认识 OpenCode 的核心配置文件 opencode.json
[ ] 修改 API 配置，让 OpenCode 连接到不同的 AI 模型（如智谱 GLM-4.7）
[ ] 调整界面主题、字体等，打造符合个人习惯的编辑器
[ ] 配置常用快捷键，提升操作效率
[ ] 通过一个完整的配置示例，理解各个配置项的作用

最终效果

你将成功创建一个高度个性化的 OpenCode 环境。它将连接到你指定的 AI 模型，使用你喜欢的暗色主题和代码字体，并且你设置的快捷键（如 Ctrl+Shift+N 新建会话）会立即生效。

前置准备

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

检查项	要求	验证方法
OpenCode	已安装	在终端输入 `opencode --version` 并看到版本号
文本编辑器	任意	如 VS Code, Sublime Text, Notepad++ 等
基本概念	了解 `AGENTS.md` 的作用	已完成相关入门课程

1. 打开配置文件

OpenCode 的配置文件 opencode.json 位于你的用户主目录。OpenCode 提供了一个快捷命令来打开它。

bash

$ opencode config edit

✅ 验证：执行命令后，你的默认文本编辑器应该会打开一个名为 opencode.json 的文件。

💡 提示：如果命令无法执行，或者你想手动编辑，配置文件位于以下位置：

macOS / Linux: ~/.opencode/opencode.json
Windows: %USERPROFILE%\.opencode\opencode.json

第 1 步：配置 API 连接（连接你的 AI 大脑）

🎯 目标：配置 OpenCode 的 API 信息，让它能连接到指定的 AI 模型（本例中使用智谱 AI 的 glm-4.7 模型）。

📝 操作：

在打开的 opencode.json 文件中，你会看到一个初始的 JSON 对象。在 { 的大括号内，添加（或替换）以下 api 配置块。

json

{
  // 新增：API 配置
  "api": {
    "provider": "zhipu",          // 模型提供商，这里是智谱 AI
    "model": "glm-4.7",           // 模型名称
    "apiKey": "your-zhipu-api-key-here", // 你的 API 密钥（重要！）
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4", // API 请求地址
    "timeout": 60000,             // 请求超时时间（毫秒）
    "maxTokens": 16384            // 单次响应最大 Token 数
  }
}

🤔 为什么要这样配置？

provider 和 model 告诉 OpenCode 你想用哪个 AI。
apiKey 是你的身份凭证，用于访问该 AI 的服务。
baseUrl 是 API 的服务器地址。通常不需要修改，除非你使用代理或自定义端点。

将 "your-zhipu-api-key-here" 替换为你的真实 API 密钥。你可以在智谱 AI 开放平台获取。
保存文件。

✅ 验证：在终端中，向 OpenCode 发送一条消息：

text

你好，请介绍一下你自己

你应该会看到 AI 的回复，并且回复内容符合智谱 AI 模型（如 glm-4.7）的风格。

⚠️ 常见错误：

API 连接失败 或 认证失败：很可能是 apiKey 填写错误。请检查密钥是否完整、有无多余空格。
超时：可以尝试增大 timeout 的值，或者检查你的网络连接是否稳定。

第 2 步：调整 UI 界面（打造你的专属编辑器）

🎯 目标：修改界面主题、字体大小和字体，让 OpenCode 更符合你的视觉习惯。

📝 操作：

在 opencode.json 文件中，添加（或替换）以下 ui 配置块。

json

{
  // 新增：UI 配置
  "ui": {
    "theme": "dark",          // 主题：dark, light, system（跟随系统）
    "language": "zh-CN",      // 界面语言
    "fontSize": 16,           // 代码字体大小
    "fontFamily": "JetBrains Mono", // 代码字体（需系统已安装）
    "tabSize": 2,             // Tab 键宽度（空格数）
    "wordWrap": true,         // 自动换行
    "minimap": false          // 是否显示右侧代码小地图
  }
}

保存文件。
重启 OpenCode，使配置生效。

✅ 验证：重启 OpenCode 后，你会看到：

界面变成了深色主题（dark）。
代码字体变成了 JetBrains Mono（如果安装了的话），字号也变大了。
长代码行会自动换行。

💡 提示：你可以随时修改这些值来尝试不同的风格。

第 3 步：配置常用快捷键（让操作快人一步）

🎯 目标：自定义你习惯的快捷键组合，提高操作效率。

📝 操作：

在 opencode.json 文件中，添加（或替换）以下 keybindings 配置块。

json

{
  // 新增：快捷键配置
  "keybindings": {
    "toggleTerminal": "ctrl+`",       // 切换终端面板
    "newSession": "ctrl+shift+n",     // 新建 AI 会话
    "runCode": "ctrl+enter",          // 运行当前代码块
    "formatCode": "ctrl+shift+f",     // 格式化代码
    "toggleSidebar": "ctrl+b"         // 切换侧边栏
  }
}

保存文件，并重启 OpenCode。

✅ 验证：

按下 Ctrl+Shift+N（Windows/Linux）或 Cmd+Shift+N（macOS），看看是否新建了一个 AI 对话。
按下 Ctrl+B，看看侧边栏是否显示或隐藏。

⚠️ 常见错误：

快捷键无效：可能与你操作系统或其他软件的快捷键冲突。例如，Ctrl+C 在终端中是复制命令，但在 OpenCode 中可能被定义为其他功能。请尝试更换一个不冲突的组合键，如 Ctrl+Shift+C。

进阶技巧（可选）

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

使用环境变量保护 API Key：为了避免 API Key 直接写在配置文件中（有泄露风险），可以使用环境变量。
json
```
{
  "api": {
    "apiKey": "${ZHIPU_API_KEY}" // 从环境变量 ZHIPU_API_KEY 中读取
  }
}
```
然后，在终端中设置环境变量 export ZHIPU_API_KEY="你的真实密钥"（macOS/Linux）或 setx ZHIPU_API_KEY "你的真实密钥"（Windows）。

配置文件排除：让 OpenCode 在分析项目时忽略某些文件夹（如 node_modules），可以加快索引速度。

json

{
  "files": {
    "exclude": [
      "node_modules/**",  // 忽略 node_modules 目录
      "dist/**",          // 忽略构建产物目录
      "*.log"             // 忽略所有日志文件
    ]
  }
}

常见问题 (FAQ)

Q1: 我修改了配置，但重启后没有任何变化，为什么？A: 最可能的原因是 opencode.json 文件格式错误，比如缺少逗号、多了一个括号。你可以使用在线的 JSON 验证工具（如 JSONLint）检查文件内容。确保 JSON 是有效的。

Q2: 我配置了 theme: "dark"，但重启后还是亮色主题？A: 请确认你保存了文件，并且完全退出并重新启动了 OpenCode。仅仅是关闭窗口可能不会触发配置重载。如果问题依旧，检查 JSON 格式是否正确。

Q3: 如何恢复到默认配置？A: 你可以备份当前的 opencode.json，然后删除它。重启 OpenCode 后，它会自动生成一个包含默认配置的新文件。

总结

恭喜你完成了本教程！🎉

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

配置文件位置：opencode.json 位于用户主目录，可通过 opencode config edit 命令快速打开。
API 配置：通过 api 配置块，可以连接不同的 AI 模型，密钥应妥善保管。
UI 个性化：通过 ui 配置块，可以调整主题、字体、字号等视觉元素。
快捷键定制：通过 keybindings 配置块，可以提升操作效率。
配置生效：修改配置文件后，通常需要重启 OpenCode 才能生效。

下一步

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

📖 OpenCode 进阶配置：学习如何配置 terminal（终端）、extensions（插件）等更高级的选项，打造一个更强大的开发环境。
📖 AGENTS.md 详解：深入理解 OpenCode 的核心概念，学习如何编写高效的 Agent 指令。

💡 练习任务：尝试修改本教程的配置，使用 deepseek 提供商和 deepseek-chat 模型，并设置一个你喜欢的 light（亮色）主题。这是巩固知识的最佳方式。


```yaml

## 相关文档

- [OpenCode 配置实战教程：从零开始定制你的 AI 编码助手](/docs/she-zhi-tiao-you/opencode-pei-zhi-shi-zhan-jiao-cheng-cong-ling-kai-shi-ding-zhi-ni-de-ai-bian-ma-zhu-shou.html)

OpenCode 个性化配置实战教程 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 打开配置文件 ​

第 1 步：配置 API 连接（连接你的 AI 大脑） ​

第 2 步：调整 UI 界面（打造你的专属编辑器） ​

第 3 步：配置常用快捷键（让操作快人一步） ​

进阶技巧（可选） ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode 个性化配置实战教程

你将学到什么

最终效果

前置准备

1. 打开配置文件

第 1 步：配置 API 连接（连接你的 AI 大脑）

第 2 步：调整 UI 界面（打造你的专属编辑器）

第 3 步：配置常用快捷键（让操作快人一步）

进阶技巧（可选）

常见问题 (FAQ)

总结

下一步