Opencode 进阶配置实战教程：打造你的 AI 编程环境

📚 分类: 环境配置 ⏱️ 预计耗时: 30-45 分钟 🎯 难度: 中级 🔧 环境要求: 已安装 Opencode (任意版本)

---

你将学到什么

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

• [ ] 理解 Opencode 配置文件 (opencode.json) 的结构和核心配置项
• [ ] 独立配置本地模型 (Ollama) 和远程 API (DeepSeek)
• [ ] 自定义快捷键，提升操作效率
• [ ] 配置工作区、权限和隐私选项，打造安全高效的开发环境
• [ ] 掌握团队共享配置的方法，统一团队开发规范

最终效果

你将拥有一份高度定制化的 Opencode 配置文件，它能够：

• 自动选择模型：根据任务复杂度，智能调用不同模型（如用轻量模型处理简单任务，用强大模型处理复杂需求）。
• 安全可控：明确读写权限，自动忽略敏感文件和目录。
• 团队统一：项目配置可以协同，团队成员开箱即用，保持开发环境一致。
• 高效操作：通过自定义快捷键，常用操作一键触发。

---

前置准备

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

检查项	要求版本	验证命令
Opencode	任意版本	opencode --version (在终端中)

1. 找到配置文件

Opencode 的核心配置文件是一个名为 opencode.json 的 JSON 文件。它的位置取决于你的操作系统：

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

你可以在终端中用以下命令快速打开它（如果文件不存在，命令会自动创建）：

# macOS / Linux
$ open ~/.config/opencode/opencode.json

# Windows (在 PowerShell 中)
$ code $env:USERPROFILE\.config\opencode\opencode.json

✅ 验证：执行命令后，你应该能看到一个文本编辑器（如 VS Code、记事本）打开了一个文件。即使文件是空的，也说明路径正确。

2. 了解配置文件格式

Opencode 的配置文件使用 JSONC 格式，这意味着你可以在文件里写注释，方便记录配置的作用。

💡 提示：JSONC 是 JSON with Comments 的缩写，它允许使用 // 单行注释和 /* */ 多行注释。

---

第 1 步：配置编辑器外观与基础行为

🎯 目标：定制编辑器的字体、主题、自动保存等基础设置，使其更符合你的编码习惯。

📝 操作： 打开 opencode.json 文件，输入以下内容。这些配置与 VS Code 的配置体系兼容，如果你用过 VS Code，会感觉很熟悉。

{
  // 编辑器外观设置
  "editor.fontSize": 14,                    // 字体大小
  "editor.fontFamily": "JetBrains Mono, Consolas, monospace", // 字体，按优先级排列
  "editor.lineHeight": 1.6,                 // 行高
  "editor.tabSize": 2,                      // Tab 缩进空格数

  // 主题选择
  "theme": "opencode-dark",                 // 或 "opencode-light"

  // 终端设置
  "terminal.shell": "zsh",                  // macOS/Linux 默认 shell
  // "terminal.shell": "powershell",        // Windows 默认 shell

  // 自动保存设置
  "files.autoSave": "afterDelay",           // 延迟后自动保存
  "files.autoSaveDelay": 1000               // 延迟时间（毫秒）
}

🤔 为什么要这样做？ 这些配置能立刻改善你的编码体验。比如，autoSave 功能可以让你无需频繁按 Ctrl+S，专注于代码本身。theme 则能根据环境光线或个人喜好，减轻视觉疲劳。

✅ 验证： 保存文件并重启 Opencode。你会看到字体、主题、自动保存行为等已经按照你的设置生效。

---

第 2 步：配置 AI 模型（核心）

🎯 目标：配置 Opencode 使用的 AI 模型，包括主模型、小模型，以及如何使用本地模型 (Ollama) 或远程 API (DeepSeek)。

2.1 基础模型配置

📝 操作： 在 opencode.json 中，添加或修改以下 model 和 small_model 配置项。

{
  // ... 之前的配置

  // 主模型：用于复杂任务，如代码重构、架构设计
  "model": "anthropic/claude-sonnet-4-5",

  // 小模型：用于简单任务，如为函数生成标题、代码补全
  "small_model": "anthropic/claude-haiku-4-5",

  // AI 自动建议
  "ai.autoSuggest": true,
  "ai.suggestionDelay": 500,                // 建议延迟（毫秒）

  // 内联代码补全
  "ai.inlineCompletion": true
}

🤔 为什么要这样做？model 和 small_model 是 Opencode 的"双引擎"策略。对于简单任务使用小模型，速度快、成本低；对于复杂任务使用大模型，理解力强、生成质量高。这能让你在效率和性能之间取得最佳平衡。

2.2 配置本地模型 (Ollama)

如果你希望完全免费且离线使用 AI，Ollama 是一个绝佳选择。

📝 操作：

1. 安装 Ollama：访问 ollama.ai 下载并安装。

2. 下载模型：打开终端，运行以下命令下载编程专用模型。

   $ ollama pull deepseek-coder   # 编程能力强，约 6.7GB
   $ ollama pull qwen2.5-coder    # 轻量级编程模型，约 4.7GB

3. 启动 Ollama 服务：

   $ ollama serve

   ⚠️ 注意：这个命令会保持终端运行。你可以另开一个终端窗口，或者将 Ollama 设置为开机自启。

4. 配置 Opencode：在 opencode.json 中添加 provider 配置，告诉 Opencode 如何连接到你的本地 Ollama 服务。

   {
     // ... 之前的配置
   
     "provider": {
       "ollama": {
         "npm": "@ai-sdk/openai-compatible", // 固定值，不要修改
         "name": "Ollama (本地)",
         "options": {
           "baseURL": "http://localhost:11434/v1" // Ollama 服务默认地址
         },
         "models": {
           "deepseek-coder": {
             "name": "DeepSeek Coder",
             "contextWindow": 16384
           },
           "qwen2.5-coder": {
             "name": "Qwen 2.5 Coder",
             "contextWindow": 32768
           }
         }
       }
     },
     // 将默认模型设置为本地模型
     "model": "ollama/deepseek-coder"
   }

✅ 验证： 重启 Opencode，在聊天框中输入 /models 命令。你应该能看到 Ollama 下的模型列表，如 ollama/deepseek-coder。

2.3 配置远程 API (DeepSeek)

DeepSeek 提供极具性价比的 API 服务，是云端方案的好选择。

📝 操作：

1. 获取 API Key：

   • 访问 platform.deepseek.com 并注册。
   • 充值（最低 10 元）。
   • 创建一个 API Key 并复制。

2. 配置 Opencode：在 opencode.json 中添加 DeepSeek 的 provider 配置。

   {
     // ... 之前的配置
   
     "provider": {
       // ... 其他 provider 配置
       "deepseek": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "DeepSeek",
         "options": {
           "baseURL": "https://api.deepseek.com/v1",
           // 推荐从环境变量读取，避免硬编码
           "apiKey": "{env:DEEPSEEK_API_KEY}"
         },
         "models": {
           "deepseek-chat": {
             "name": "DeepSeek Chat"
           },
           "deepseek-coder": {
             "name": "DeepSeek Coder"
           }
         }
       }
     },
     // 将默认模型切换为 DeepSeek
     "model": "deepseek/deepseek-coder"
   }

   💡 提示：{env:DEEPSEEK_API_KEY} 是 Opencode 支持的环境变量引用语法。这比直接把 API Key 写在配置文件里更安全。

3. 设置环境变量：

   • macOS / Linux：编辑 ~/.zshrc 或 ~/.bashrc，添加一行：

     export DEEPSEEK_API_KEY="你的API密钥"

     然后运行 source ~/.zshrc 使其生效。
   • Windows (PowerShell)：运行以下命令：

     [Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "你的API密钥", "User")

✅ 验证： 重启 Opencode，在聊天框中输入一个简单问题（如 "你好"）。如果 DeepSeek 模型能够正常回复，说明配置成功。

2.4 多模型策略

你可以配置多个模型，让 Opencode 根据任务自动选择。

📝 操作： 在 opencode.json 中，配置 enabled_providers 和 disabled_providers。

{
  // 主模型：用于复杂任务
  "model": "anthropic/claude-opus-4-5",
  // 小模型：用于简单任务
  "small_model": "deepseek/deepseek-coder",

  // 启用的 Provider 列表
  "enabled_providers": ["anthropic", "deepseek", "ollama"],
  // 禁用的 Provider
  "disabled_providers": []
}

🤔 为什么要这样做？ 通过 enabled_providers，你可以精确控制 Opencode 可以使用的模型来源。例如，你可以在开发时启用所有模型，在发布构建时只启用快速且稳定的 deepseek 模型，以提高效率。

---

第 3 步：自定义快捷键

🎯 目标：将常用的 Opencode 功能绑定到你习惯的快捷键上，大幅提升操作速度。

📝 操作：

1. 查看当前快捷键：在 Opencode 中按下 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows)，输入 "Keyboard Shortcuts" 并选择，即可查看所有可用的命令和快捷键。

2. 创建/编辑快捷键配置文件：编辑 ~/.config/opencode/keybindings.json (macOS/Linux) 或 %USERPROFILE%\.config\opencode\keybindings.json (Windows)。

3. 添加自定义快捷键：以下是一些推荐的快捷键配置：

   [
     {
       "key": "cmd+k",               // 你希望使用的快捷键
       "command": "opencode.inlineEdit",  // 触发的 Opencode 命令
       "when": "editorTextFocus"     // 触发条件：当编辑器获得焦点时
     },
     {
       "key": "cmd+l",
       "command": "opencode.chatView"
     },
     {
       "key": "cmd+.",
       "command": "opencode.explainCode",
       "when": "editorHasSelection"  // 当编辑器中有选中文本时
     },
     {
       "key": "cmd+shift+k",
       "command": "opencode.generateTests",
       "when": "editorTextFocus"
     }
   ]

✅ 验证： 保存文件后，立即生效。你可以尝试按下 Cmd+K (或 Ctrl+K)，看是否会触发内联编辑功能。如果没有任何反应，检查快捷键是否有冲突或配置是否正确。

---

第 4 步：配置工作区、隐私与权限

🎯 目标：为项目创建独立的配置，并设置好权限和隐私选项，确保开发过程安全可控。

4.1 项目级配置

你可以为每个项目创建独立的配置，覆盖全局设置。

📝 操作： 在项目根目录下创建一个 opencode.json 文件（或 .opencode/opencode.json 目录）。

// 项目根目录 / opencode.json
{
  // 项目特定的模型
  "model": "deepseek/deepseek-coder",

  // 项目特定的权限
  "permission": {
    "bash": {
      "*": "ask",                // 默认：执行任何 bash 命令前询问
      "npm test": "allow",       // 允许自动运行 npm test
      "npm run build": "allow"   // 允许自动运行 npm run build
    }
  },

  // 项目特定的忽略规则
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**"
    ]
  }
}

🤔 为什么要这样做？ 项目级配置会覆盖全局配置。这意味着你可以为不同项目设置不同的模型（如前端项目用 deepseek-coder，后端项目用 claude-opus），或者为特定项目开放特定的 bash 命令权限，实现精细化管理。

4.2 隐私与安全设置

📝 操作：

禁用遥测：

{
  // ... 其他配置
  "telemetry": {
    "enabled": false
  }
}

配置权限：

{
  // ... 其他配置
  "permission": {
    "read": {
      "*": "allow",              // 默认允许读取所有文件
      "*.env": "deny",           // 禁止读取 .env 文件
      "*.key": "deny"            // 禁止读取 .key 文件
    },
    "edit": "ask",               // 修改文件前需要询问
    "bash": "ask"                // 执行 bash 命令前需要询问
  }
}

⚠️ 常见错误： 如果你不小心阻止了 Opencode 读取某个必要的配置文件，它可能会报错。此时，你可以临时将 "*.env": "deny" 改为 "*.env": "ask"，这样每次读取前都会询问你，更加灵活。

4.3 上下文压缩与索引配置

为了避免 Token 超限和提升性能，可以进行以下设置。

📝 操作：

{
  // 上下文压缩
  "compaction": {
    "auto": true,          // 自动压缩上下文
    "prune": true,         // 删除旧的工具输出
    "threshold": 0.8       // 当上下文使用率达到 80% 时触发压缩
  },

  // 索引配置
  "indexing": {
    "auto": true,          // 自动索引项目文件
    "maxFileSize": 1048576, // 索引的最大文件大小（1MB）
    "exclude": [
      "node_modules/**",
      "*.min.js",
      "*.map"
    ]
  }
}

---

第 5 步：团队共享配置

🎯 目标：将项目配置提交到 Git 仓库，确保团队成员拥有相同的 Opencode 开发环境。

📝 操作：

1. 创建项目级配置文件：按照第 4.1 步，在项目根目录创建 opencode.json。

2. 提交到 Git：

   $ git add opencode.json
   $ git commit -m "chore: add Opencode project configuration"
   $ git push

3. 团队成员克隆项目后：配置会自动生效。opencode.json 中不应包含任何敏感信息（如 API Key），应使用环境变量引用。

示例：团队共享的 opencode.json

// 项目根目录 / opencode.json
{
  // 团队统一的模型
  "model": "anthropic/claude-sonnet-4-5",

  // 团队统一的编码规范
  "editor.tabSize": 2,
  "editor.insertSpaces": true,

  // 敏感信息使用环境变量
  "provider": {
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    }
  }
}

---

进阶技巧（可选）

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

1. 安装扩展插件：Opencode 兼容 VS Code 插件市场。按下 Cmd+Shift+X (macOS) / Ctrl+Shift+X (Windows) 搜索并安装，如 ESLint、Prettier、GitLens 等。
2. 配置文件监控忽略规则：在 watcher.ignore 中添加更多你不需要监控的目录，如 build/、target/、venv/ 等，可以提升性能。
3. 使用 $schema 获得智能提示：在 opencode.json 文件顶部添加 "$schema": "https://opencode.ai/config.json"，许多编辑器会提供自动补全和校验功能。

---

常见问题 (FAQ)

Q1: 配置修改后不生效？A: 大多数配置保存后立即生效。如果某些配置（如模型切换）没有生效，请重启 Opencode。按 Cmd+Q (macOS) 或 Alt+F4 (Windows) 退出，然后重新启动。

Q2: 如何重置所有配置？A: 删除配置文件即可。

• macOS/Linux: rm ~/.config/opencode/opencode.json
• Windows: 删除 %USERPROFILE%\.config\opencode\opencode.json 文件 重启 Opencode 后，它会自动生成一份默认配置。

Q3: 如何备份我的配置？A: 很简单，复制文件即可。

$ cp ~/.config/opencode/opencode.json ~/opencode-backup.json

Q4: 报错 module not found 或 connect ECONNREFUSED 怎么办？A:

• 如果是 Ollama 报错，请确认 ollama serve 服务正在运行。
• 如果是 DeepSeek 报错，请检查 apiKey 是否正确，以及环境变量是否设置成功。

---

总结

恭喜你完成了本教程！🎉

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

1. 配置文件基础：掌握了 opencode.json 的位置、格式和基础配置（外观、主题、自动保存）。
2. 模型配置：学会了配置主模型、小模型，以及如何集成本地模型 (Ollama) 和远程 API (DeepSeek)。
3. 效率提升：通过自定义快捷键，显著提升了操作效率。
4. 环境管理：能够为项目创建独立配置，并设置权限、隐私、上下文压缩等高级选项。
5. 团队协作：掌握了通过 Git 共享项目配置，统一团队开发环境的方法。

---