进阶配置

当熟悉了 Opencode 的基本操作后，你可以通过配置文件来定制更强大的工作流。本文将带你深入了解 Opencode 的配置体系。

配置文件位置

Opencode 的配置文件位于：

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

你可以直接编辑这个文件，也可以通过 Opencode 的设置界面修改。

配置文件格式

Opencode 支持 JSONC 格式（JSON with Comments），你可以添加注释：

{
  "$schema": "https://opencode.ai/config.json",
  
  // 编辑器设置
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  
  /* AI 模型配置 */
  "model": "anthropic/claude-sonnet-4-5",
  
  // 自动更新
  "autoupdate": true
}

基础配置

编辑器设置

Opencode 兼容 VS Code 的配置体系：

{
  // 编辑器外观
  "editor.fontSize": 14,
  "editor.fontFamily": "JetBrains Mono, Consolas, monospace",
  "editor.lineHeight": 1.6,
  "editor.tabSize": 2,
  
  // 主题
  "theme": "opencode-dark",  // 或 "opencode-light"
  
  // 终端
  "terminal.shell": "zsh",  // macOS/Linux
  // "terminal.shell": "powershell",  // Windows
  
  // 自动保存
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000
}

AI 模型配置

{
  // 主模型（用于复杂任务）
  "model": "anthropic/claude-sonnet-4-5",
  
  // 小模型（用于简单任务，如生成标题）
  "small_model": "anthropic/claude-haiku-4-5",
  
  // AI 自动建议
  "ai.autoSuggest": true,
  "ai.suggestionDelay": 500,  // 毫秒
  
  // 自动补全
  "ai.inlineCompletion": true
}

配置自定义模型

使用 Ollama（本地模型）

Ollama 让你可以完全免费在本地运行 AI 模型。

1. 安装 Ollama

访问 ollama.ai 下载并安装。

2. 下载模型

# 推荐用于编程的模型
ollama pull deepseek-coder      # 6.7GB，编程能力强
ollama pull qwen2.5-coder       # 4.7GB，轻量级
ollama pull llama3              # 4.7GB，通用能力强

# 查看已下载的模型
ollama list

3. 启动 Ollama 服务

ollama serve

4. 配置 Opencode

编辑 ~/.config/opencode/opencode.json：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (本地)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "deepseek-coder": {
          "name": "DeepSeek Coder",
          "contextWindow": 16384
        },
        "qwen2.5-coder": {
          "name": "Qwen 2.5 Coder",
          "contextWindow": 32768
        },
        "llama3": {
          "name": "Llama 3",
          "contextWindow": 8192
        }
      }
    }
  },
  
  // 设置为默认模型
  "model": "ollama/deepseek-coder"
}

5. 验证配置

重启 Opencode，运行 /models 命令，应该能看到 Ollama 的模型。

使用 DeepSeek API

DeepSeek 提供极具性价比的 API 服务（约 ¥0.001/1K tokens）。

1. 获取 API Key

访问 platform.deepseek.com
注册并充值（最低 10 元）
创建 API Key

2. 配置 Opencode

方法 A：使用命令

# 在 Opencode 中运行
/connect

# 选择 DeepSeek
# 输入 API Key

方法 B：编辑配置文件

{
  "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"
        }
      }
    }
  },
  
  "model": "deepseek/deepseek-coder"
}

3. 设置环境变量

macOS/Linux

编辑 ~/.zshrc 或 ~/.bashrc：

export DEEPSEEK_API_KEY="your-api-key-here"

然后运行：

source ~/.zshrc

Windows

在 PowerShell 中：

[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "your-api-key-here", "User")

使用 Claude Pro/ChatGPT Plus 订阅

如果你有现有订阅，可以直接使用，无需额外购买 API。

详细配置方法：Provider 配置完全指南

多模型策略

配置多个模型，让 Opencode 根据任务自动选择：

{
  // 主模型：用于复杂任务
  "model": "anthropic/claude-opus-4-5",
  
  // 小模型：用于简单任务
  "small_model": "deepseek/deepseek-coder",
  
  // 启用的 Provider
  "enabled_providers": ["anthropic", "deepseek", "ollama"],
  
  // 禁用的 Provider
  "disabled_providers": []
}

Opencode 会根据任务复杂度自动选择合适的模型：

生成标题、简单补全 → 使用 small_model
复杂重构、架构设计 → 使用 model

快捷键自定义

查看当前快捷键

按 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows)，输入 "Keyboard Shortcuts"。

自定义快捷键

编辑 ~/.config/opencode/keybindings.json：

[
  {
    "key": "cmd+k",
    "command": "opencode.inlineEdit",
    "when": "editorTextFocus"
  },
  {
    "key": "cmd+l",
    "command": "opencode.chatView"
  },
  {
    "key": "cmd+.",
    "command": "opencode.explainCode",
    "when": "editorHasSelection"
  },
  {
    "key": "cmd+shift+k",
    "command": "opencode.generateTests",
    "when": "editorTextFocus"
  }
]

功能	macOS	Windows/Linux
Inline Edit	`Cmd+K`	`Ctrl+K`
Chat View	`Cmd+L`	`Ctrl+L`
Explain Code	`Cmd+.`	`Ctrl+.`
Generate Tests	`Cmd+Shift+K`	`Ctrl+Shift+K`
Refactor	`Cmd+Shift+R`	`Ctrl+Shift+R`

性能优化

文件监控配置

大型项目需要配置忽略规则，避免 CPU 占用过高：

{
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      "build/**",
      ".git/**",
      ".next/**",
      "target/**",
      "venv/**",
      "__pycache__/**",
      "*.log",
      ".DS_Store"
    ]
  }
}

上下文压缩

避免 Token 超限：

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

索引配置

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

隐私与安全

禁用遥测

{
  "telemetry": {
    "enabled": false
  }
}

配置权限

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.key": "deny"
    },
    "edit": "ask",
    "bash": "ask"
  }
}

详细配置：权限与安全配置

工作区配置

项目级配置

在项目根目录创建 opencode.json 或 .opencode/opencode.json：

{
  // 项目特定的模型
  "model": "deepseek/deepseek-coder",
  
  // 项目特定的权限
  "permission": {
    "bash": {
      "*": "ask",
      "npm test": "allow",
      "npm run build": "allow"
    }
  },
  
  // 项目特定的忽略规则
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**"
    ]
  }
}

项目配置会覆盖全局配置。

团队共享配置

将 opencode.json 提交到 Git，团队成员克隆后自动生效：

{
  // 团队统一的模型
  "model": "anthropic/claude-sonnet-4-5",
  
  // 团队统一的编码规范
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  
  // 敏感信息使用环境变量
  "provider": {
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    }
  }
}

插件与扩展

安装插件

按 Cmd+Shift+X (macOS) 或 Ctrl+Shift+X (Windows)
搜索插件名称
点击安装

完整配置示例

最小化配置

适合快速开始：

{
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

本地开发配置

完全使用本地模型：

{
  "model": "ollama/deepseek-coder",
  "enabled_providers": ["ollama"],
  "telemetry": {
    "enabled": false
  },
  "watcher": {
    "ignore": ["node_modules/**", "dist/**"]
  }
}

生产级配置

适合团队协作：

{
  "$schema": "https://opencode.ai/config.json",
  
  // 模型配置
  "model": "anthropic/claude-opus-4-5",
  "small_model": "deepseek/deepseek-coder",
  
  // 权限严格控制
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.key": "deny"
    },
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "npm test": "allow"
    }
  },
  
  // 性能优化
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      ".git/**"
    ]
  },
  
  // 自动压缩
  "compaction": {
    "auto": true,
    "prune": true
  },
  
  // 编辑器设置
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "files.autoSave": "afterDelay"
}

常见问题

Q: 配置修改后不生效？

A: 某些配置需要重启 Opencode。按 Cmd+Q (macOS) 或 Alt+F4 (Windows) 退出，然后重新启动。

Q: 如何重置配置？

A: 删除配置文件：

rm ~/.config/opencode/opencode.json

重启 Opencode 会生成默认配置。

Q: 配置文件在哪里？

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

Q: 如何备份配置？

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

下一步

Provider 配置完全指南 - 深入了解模型配置
配置文件详解 - 理解配置优先级
Agent 配置指南 - 配置 AI 团队
权限与安全配置 - 保护代码安全

配置是一次性的工作，但会带来长期的效率提升。花点时间打造最适合你的环境吧！