OpenCode 中文社区

Appearance

5.1a 配置基础 ​

💡 一句话总结：掌握 opencode.json 的基础配置项，快速上手 OpenCode 定制。

学完你能做什么 ​

  • 理解 opencode.json 的作用和结构
  • 掌握常用的配置项
  • 能根据需求调整基础配置
  • 让 OpenCode 符合你的使用习惯

你现在的困境 ​

  • 不知道 opencode.json 在哪里
  • 看到配置项不知道什么意思
  • 不知道怎么修改配置
  • 改完配置不知道是否生效

什么时候用这一招 ​

  • 当你刚开始使用 OpenCode
  • 当你需要调整基础设置
  • 当你想了解 OpenCode 的配置系统

🎒 开始前的准备 ​

确保你已经完成以下事项：

  • [ ] 完成 OpenCode 安装
  • [ ] 了解 AGENTS.md 的作用（必修课程）
  • [ ] 准备一个文本编辑器

核心思路 ​

配置文件位置 ​

OpenCode 的配置文件位于用户主目录：

系统位置
macOS/Linux~/.opencode/opencode.json
Windows%USERPROFILE%\.opencode\opencode.json

配置结构概览 ​

json
{
  "$schema": "https://opencode.ai/schema.json",
  "version": "1.0",
  "api": {
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "your-api-key"
  },
  "ui": {
    "theme": "system",
    "language": "zh-CN",
    "fontSize": 14
  },
  "features": {
    "autoComplete": true,
    "syntaxHighlight": true,
    "lineNumbers": true
  }
}

常用配置项详解 ​

API 配置 ​

json
{
  "api": {
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "your-api-key-here",
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
    "timeout": 60000,
    "maxTokens": 16384
  }
}
配置项说明示例值
provider模型提供商zhipu、deepseek、openai
model模型名称glm-4.7、gpt-4、deepseek-chat
apiKeyAPI 密钥你的密钥
baseUrlAPI 地址可选，自定义端点
timeout超时时间(毫秒)60000
maxTokens最大 Token 数16384

UI 配置 ​

json
{
  "ui": {
    "theme": "dark",
    "language": "zh-CN",
    "fontSize": 16,
    "fontFamily": "JetBrains Mono",
    "tabSize": 2,
    "wordWrap": true,
    "minimap": false
  }
}
配置项说明示例值
theme主题dark、light、system
language语言zh-CN、en-US
fontSize字体大小14、16
fontFamily字体JetBrains Mono、Fira Code
tabSizeTab 宽度2、4
wordWrap自动换行true、false
minimap显示小地图true、false

功能配置 ​

json
{
  "features": {
    "autoComplete": true,
    "syntaxHighlight": true,
    "lineNumbers": true,
    "bracketPairColorization": true,
    "autoClosingBrackets": "always",
    "autoClosingQuotes": "beforeSpace",
    "formatOnSave": true
  }
}

快捷键配置 ​

json
{
  "keybindings": {
    "toggleTerminal": "ctrl+`",
    "newSession": "ctrl+shift+n",
    "runCommand": "ctrl+enter",
    "copyCode": "ctrl+c"
  }
}

文件排除配置 ​

json
{
  "files": {
    "exclude": [
      "node_modules/**",
      "dist/**",
      "build/**",
      "*.log",
      ".git/**"
    ],
    "watch": true,
    "autoRefresh": true
  }
}

跟我做 ​

实战 1：配置智谱 GLM-4.7 ​

目标：让 OpenCode 使用智谱模型

  1. 打开配置文件：
bash
opencode config edit
  1. 添加 API 配置：
json
{
  "api": {
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "your-zhipu-api-key"
  }
}

  1. 保存并重启 OpenCode

  2. 测试配置是否生效：

你好，请介绍一下你自己

你应该看到：AI 使用智谱模型回复

实战 2：调整界面设置 ​

目标：让界面更符合你的习惯

  1. 编辑配置文件：
json
{
  "ui": {
    "theme": "dark",
    "fontSize": 16,
    "fontFamily": "JetBrains Mono"
  }
}

  1. 保存配置

  2. 重启 OpenCode

你应该看到：界面变成暗色主题，字体变大

实战 3：配置常用快捷键 ​

目标：设置你习惯的快捷键

  1. 编辑配置文件：
json
{
  "keybindings": {
    "toggleTerminal": "ctrl+`",
    "newSession": "ctrl+shift+n",
    "runCode": "ctrl+enter",
    "formatCode": "ctrl+shift+f"
  }
}
  1. 测试快捷键是否生效

你应该看到：快捷键按预期工作

📋 完整配置示例 ​

json
{
  "$schema": "https://opencode.ai/schema.json",
  "version": "1.0",
  "api": {
    "provider": "zhipu",
    "model": "glm-4.7",
    "apiKey": "${ZHIPU_API_KEY}",
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
    "timeout": 60000,
    "maxTokens": 16384
  },
  "ui": {
    "theme": "dark",
    "language": "zh-CN",
    "fontSize": 14,
    "fontFamily": "JetBrains Mono",
    "tabSize": 2,
    "wordWrap": true,
    "minimap": false,
    "smoothScrolling": true
  },
  "features": {
    "autoComplete": true,
    "syntaxHighlight": true,
    "lineNumbers": true,
    "bracketPairColorization": true,
    "autoClosingBrackets": "always",
    "formatOnSave": true,
    "autoSave": "afterDelay",
    "autoSaveDelay": 1000
  },
  "keybindings": {
    "toggleTerminal": "ctrl+`",
    "newSession": "ctrl+shift+n",
    "runCode": "ctrl+enter",
    "formatCode": "ctrl+shift+f",
    "toggleSidebar": "ctrl+b"
  },
  "files": {
    "exclude": [
      "node_modules/**",
      "dist/**",
      "build/**",
      "*.log",
      ".git/**",
      ".vscode/**"
    ],
    "watch": true,
    "autoRefresh": true,
    "defaultLanguage": "typescript"
  },
  "terminal": {
    "shell": "/bin/zsh",
    "fontSize": 13,
    "fontFamily": "JetBrains Mono",
    "cursorStyle": "block",
    "cursorBlink": true
  },
  "extensions": {
    "enabled": true,
    "autoUpdate": true,
    "trustedExtensions": []
  }
}

检查点 ✅ ​

全部通过才能继续

  • [ ] 知道配置文件在哪里
  • [ ] 能修改 API 配置
  • [ ] 能调整界面设置
  • [ ] 能配置快捷键

踩坑提醒 ​

现象原因解决
配置不生效配置文件格式错误用 JSON 验证工具检查
API 连接失败API Key 错误检查密钥是否正确
主题不变未重启保存后重启 OpenCode
快捷键冲突与系统快捷键冲突更换快捷键组合

本课小结 ​

你学会了：

  1. OpenCode 配置文件的位置和结构
  2. 常用配置项的作用和设置方法
  3. API、UI、功能、快捷键的配置
  4. 完整的配置示例参考

下一课预告 ​

下一课我们将学习进阶配置，掌握更多高级配置项和优化技巧。

📚 更多完整模板：Prompt 模板库

微信群