📚 本系列目录：《OpenCode 深度解析》当前第 7/11 篇 · 上一篇：OpenCode TUI 界面实现：Elm 架构与 Bubble Tea 的深度应用 | 深度解析（五） · 下一篇：OpenCode LSP 集成：Language Server Protocol 架构与实现 | 深度解析（七）

📚 系列导航

《OpenCode 深度解析》共 11 篇，本篇是第 7 篇。

← 上一篇：OpenCode TUI 界面实现：Elm 架构与 Bubble Tea 的深度应用 | 深度解析（五）

下一篇：OpenCode LSP 集成：Language Server Protocol 架构与实现 | 深度解析（七） →

OpenCode 配置系统：多层级配置合并与 Provider 自动选择机制

引言

一个优秀的 CLI 工具，配置系统是其易用性的关键。OpenCode 的配置系统设计精巧，提供了：

多层级配置合并：全局 → 用户 → 项目本地
环境变量覆盖：支持 API Key 等敏感信息通过环境变量设置
智能 Provider 选择：根据已配置的 Provider 自动选择默认模型
灵活的 LSP 配置：支持自定义语言服务器

本文将深入剖析 OpenCode 的配置系统设计。

一、配置架构概述

1.1 配置层级

OpenCode 采用三层配置合并机制，优先级从低到高：

┌─────────────────────────────────────────────────────────────┐
│                    1. 内置默认值 (代码)                       │
│  - data.directory = ".opencode"                             │
│  - tui.theme = "opencode"                                  │
│  - autoCompact = true                                       │
│  - shell.path = $SHELL 或 /bin/bash                         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                 2. 全局配置文件 (~/.opencode.json)            │
│  - 用户级别的自定义配置                                       │
│  - 可配置 Provider API Keys、默认模型等                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              3. 项目本地配置 (.opencode.json)                 │
│  - 项目级别的配置                                            │
│  - LSP 配置、MCP 服务器等                                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                  4. 环境变量 (最高优先级)                     │
│  - ANTHROPIC_API_KEY                                       │
│  - OPENAI_API_KEY                                           │
│  - GEMINI_API_KEY                                           │
│  - ...                                                      │
└─────────────────────────────────────────────────────────────┘

1.2 Viper 配置框架

OpenCode 使用 Viper 管理配置，这是 Go 语言最流行的配置管理库之一：

// internal/config/config.go
import "github.com/spf13/viper"

func configureViper() {
    viper.SetConfigName(fmt.Sprintf(".%s", appName))  // 配置文件名
    viper.SetConfigType("json")                        // 配置文件类型
    viper.AddConfigPath("$HOME")                        // 用户 home 目录
    viper.AddConfigPath("$XDG_CONFIG_HOME/opencode")   // XDG 配置目录
    viper.AddConfigPath("$HOME/.config/opencode")      // 备用配置目录
    viper.SetEnvPrefix(strings.ToUpper(appName))       // 环境变量前缀
    viper.AutomaticEnv()                               // 自动读取环境变量
}

1.3 配置搜索路径

// 配置文件搜索顺序（优先级从低到高）
// 1. $HOME/.opencode.json
// 2. $XDG_CONFIG_HOME/opencode/.opencode.json
// 3. $HOME/.config/opencode/.opencode.json
// 4. <工作目录>/.opencode.json (通过 mergeLocalConfig 合并)

二、Config 数据结构

2.1 主配置结构

// internal/config/config.go
type Config struct {
    Data         Data                              `json:"data"`
    WorkingDir   string                            `json:"wd,omitempty"`
    MCPServers   map[string]MCPServer              `json:"mcpServers,omitempty"`
    Providers    map[models.ModelProvider]Provider `json:"providers,omitempty"`
    LSP          map[string]LSPConfig              `json:"lsp,omitempty"`
    Agents       map[AgentName]Agent               `json:"agents,omitempty"`
    Debug        bool                              `json:"debug,omitempty"`
    DebugLSP     bool                              `json:"debugLSP,omitempty"`
    ContextPaths []string                          `json:"contextPaths,omitempty"`
    TUI          TUIConfig                         `json:"tui"`
    Shell        ShellConfig                       `json:"shell,omitempty"`
    AutoCompact  bool                              `json:"autoCompact,omitempty"`
}

2.2 数据目录配置

type Data struct {
    Directory string `json:"directory,omitempty"`
}

// 默认值
const defaultDataDirectory = ".opencode"

数据目录是 OpenCode 存储 SQLite 数据库、日志等文件的地方，默认为 .opencode。

2.3 Provider 配置

type Provider struct {
    APIKey   string `json:"apiKey"`
    Disabled bool   `json:"disabled"`
}

// 支持的 Provider 类型
type ModelProvider string

const (
    ProviderCopilot   ModelProvider = "copilot"
    ProviderAnthropic ModelProvider = "anthropic"
    ProviderOpenAI    ModelProvider = "openai"
    ProviderGemini    ModelProvider = "gemini"
    ProviderGroq      ModelProvider = "groq"
    ProviderOpenRouter ModelProvider = "openrouter"
    ProviderXAI       ModelProvider = "xai"
    ProviderAzure     ModelProvider = "azure"
    ProviderBedrock   ModelProvider = "bedrock"
    ProviderVertexAI  ModelProvider = "vertexai"
    ProviderLocal     ModelProvider = "local"
)

2.4 Agent 配置

type Agent struct {
    Model           models.ModelID `json:"model"`
    MaxTokens       int64          `json:"maxTokens"`
    ReasoningEffort string         `json:"reasoningEffort"`  // low, medium, high
}

// 预定义的 Agent 类型
const (
    AgentCoder      AgentName = "coder"
    AgentSummarizer AgentName = "summarizer"
    AgentTask       AgentName = "task"
    AgentTitle      AgentName = "title"
)

每个 Agent 类型对应不同的用途：

Agent	用途	默认模型
coder	主要编程任务	Claude 4 Sonnet
summarizer	会话摘要	Claude 4 Sonnet
task	子 Agent 任务	Claude 4 Sonnet
title	生成会话标题	Claude 4 Sonnet (小 token)

2.5 MCP 服务器配置

type MCPServer struct {
    Command string            `json:"command"`  // 命令
    Env     []string          `json:"env"`      // 环境变量
    Args    []string          `json:"args"`     // 参数
    Type    MCPType           `json:"type"`     // stdio 或 sse
    URL     string            `json:"url"`      // SSE 模式 URL
    Headers map[string]string `json:"headers"`  // HTTP 头
}

type MCPType string
const (
    MCPStdio MCPType = "stdio"
    MCPSse   MCPType = "sse"
)

2.6 LSP 配置

type LSPConfig struct {
    Disabled bool     `json:"enabled"`
    Command  string   `json:"command"`
    Args     []string `json:"args"`
    Options  any      `json:"options"`
}

2.7 TUI 配置

type TUIConfig struct {
    Theme string `json:"theme,omitempty"`
}

type ShellConfig struct {
    Path string   `json:"path,omitempty"`
    Args []string `json:"args,omitempty"`
}

三、环境变量与 API Key 管理

3.1 环境变量检测

// internal/config/config.go
func setProviderDefaults() {
    // 依次检测各 Provider 的 API Key
    if apiKey := os.Getenv("ANTHROPIC_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.anthropic.apiKey", apiKey)
    }
    if apiKey := os.Getenv("OPENAI_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.openai.apiKey", apiKey)
    }
    if apiKey := os.Getenv("GEMINI_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.gemini.apiKey", apiKey)
    }
    if apiKey := os.Getenv("GROQ_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.groq.apiKey", apiKey)
    }
    if apiKey := os.Getenv("OPENROUTER_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.openrouter.apiKey", apiKey)
    }
    if apiKey := os.Getenv("XAI_API_KEY"); apiKey != "" {
        viper.SetDefault("providers.xai.apiKey", apiKey)
    }
    
    // Azure 使用端点环境变量
    if apiKey := os.Getenv("AZURE_OPENAI_ENDPOINT"); apiKey != "" {
        viper.SetDefault("providers.azure.apiKey", os.Getenv("AZURE_OPENAI_API_KEY"))
    }
    
    // GitHub Copilot
    if apiKey, err := LoadGitHubToken(); err == nil && apiKey != "" {
        viper.SetDefault("providers.copilot.apiKey", apiKey)
    }
}

3.2 Provider 优先级

当配置多个 Provider 时，OpenCode 按照以下优先级选择默认模型：

// Provider 选择顺序（第一个有有效 API Key 的被选中）
// 1. Copilot
// 2. Anthropic
// 3. OpenAI
// 4. Google Gemini
// 5. Groq
// 6. OpenRouter
// 7. XAI
// 8. AWS Bedrock
// 9. Azure OpenAI
// 10. Google Cloud VertexAI

每个 Provider 的默认模型：

// Copilot
if strings.TrimSpace(key) != "" {
    viper.SetDefault("agents.coder.model", models.CopilotGPT4o)
    viper.SetDefault("agents.summarizer.model", models.CopilotGPT4o)
    viper.SetDefault("agents.task.model", models.CopilotGPT4o)
    viper.SetDefault("agents.title.model", models.CopilotGPT4o)
    return  // 找到第一个有效 Provider 后返回
}

// Anthropic
if strings.TrimSpace(key) != "" {
    viper.SetDefault("agents.coder.model", models.Claude4Sonnet)
    viper.SetDefault("agents.summarizer.model", models.Claude4Sonnet)
    viper.SetDefault("agents.task.model", models.Claude4Sonnet)
    viper.SetDefault("agents.title.model", models.Claude4Sonnet)
    return
}

// OpenAI
if strings.TrimSpace(key) != "" {
    viper.SetDefault("agents.coder.model", models.GPT41)
    viper.SetDefault("agents.summarizer.model", models.GPT41)
    viper.SetDefault("agents.task.model", models.GPT41Mini)
    viper.SetDefault("agents.title.model", models.GPT41Mini)
    return
}

3.3 AWS 凭证检测

func hasAWSCredentials() bool {
    // 显式 AWS 凭证
    if os.Getenv("AWS_ACCESS_KEY_ID") != "" && os.Getenv("AWS_SECRET_ACCESS_KEY") != "" {
        return true
    }
    
    // AWS Profile
    if os.Getenv("AWS_PROFILE") != "" || os.Getenv("AWS_DEFAULT_PROFILE") != "" {
        return true
    }
    
    // AWS Region
    if os.Getenv("AWS_REGION") != "" || os.Getenv("AWS_DEFAULT_REGION") != "" {
        return true
    }
    
    // EC2 Instance Profile
    if os.Getenv("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI") != "" {
        return true
    }
    
    return false
}

四、配置加载流程

4.1 Load 函数主流程

func Load(workingDir string, debug bool) (*Config, error) {
    // 1. 单例模式：已加载则直接返回
    if cfg != nil {
        return cfg, nil
    }
    
    // 2. 初始化配置结构
    cfg = &Config{
        WorkingDir: workingDir,
        MCPServers: make(map[string]MCPServer),
        Providers:  make(map[models.ModelProvider]Provider),
        LSP:        make(map[string]LSPConfig),
    }
    
    // 3. 配置 Viper
    configureViper()
    
    // 4. 设置内置默认值
    setDefaults(debug)
    
    // 5. 读取全局配置
    if err := readConfig(viper.ReadInConfig()); err != nil {
        return cfg, err
    }
    
    // 6. 合并项目本地配置
    mergeLocalConfig(workingDir)
    
    // 7. 设置 Provider 默认值（根据环境变量）
    setProviderDefaults()
    
    // 8. 解析到 Config 结构体
    if err := viper.Unmarshal(cfg); err != nil {
        return cfg, fmt.Errorf("failed to unmarshal config: %w", err)
    }
    
    // 9. 应用默认值
    applyDefaultValues()
    
    // 10. 配置日志
    configureLogging()
    
    // 11. 验证配置
    if err := Validate(); err != nil {
        return cfg, fmt.Errorf("config validation failed: %w", err)
    }
    
    // 12. 特殊处理
    cfg.Agents[AgentTitle] = Agent{
        Model:     cfg.Agents[AgentTitle].Model,
        MaxTokens: 80,  // 标题生成只需要少量 token
    }
    
    return cfg, nil
}

4.2 本地配置合并

func mergeLocalConfig(workingDir string) {
    local := viper.New()
    local.SetConfigName(fmt.Sprintf(".%s", appName))
    local.SetConfigType("json")
    local.AddConfigPath(workingDir)
    
    if err := local.ReadInConfig(); err == nil {
        // 合并到主配置
        viper.MergeConfigMap(local.AllSettings())
    }
}

4.3 默认值应用

func applyDefaultValues() {
    // 为未指定类型的 MCP 服务器设置默认类型
    for k, v := range cfg.MCPServers {
        if v.Type == "" {
            v.Type = MCPStdio  // 默认为 stdio 模式
            cfg.MCPServers[k] = v
        }
    }
}

五、配置验证

5.1 验证流程

func Validate() error {
    // 验证每个 Agent 的配置
    for name, agent := range cfg.Agents {
        if err := validateAgent(cfg, name, agent); err != nil {
            return err
        }
    }
    return nil
}

5.2 Agent 验证

func validateAgent(cfg *Config, name AgentName, agent Agent) error {
    // 1. 检查模型是否存在
    model, modelExists := models.SupportedModels[agent.Model]
    if !modelExists {
        logging.Warn("unsupported model configured, reverting to default",
            "agent", name,
            "configured_model", agent.Model)
        
        if setDefaultModelForAgent(name) {
            logging.Info("set default model for agent", "agent", name, "model", cfg.Agents[name].Model)
        } else {
            return fmt.Errorf("no valid provider available for agent %s", name)
        }
        return nil
    }
    
    // 2. 检查 Provider 是否配置
    provider := model.Provider
    providerCfg, providerExists := cfg.Providers[provider]
    
    if !providerExists {
        // 尝试从环境变量获取
        apiKey := getProviderAPIKey(provider)
        if apiKey == "" {
            logging.Warn("provider not configured, reverting to default", ...)
            if setDefaultModelForAgent(name) {
                logging.Info("set default model for agent", ...)
            } else {
                return fmt.Errorf("no valid provider available for agent %s", name)
            }
        } else {
            cfg.Providers[provider] = Provider{APIKey: apiKey}
            logging.Info("added provider from environment", "provider", provider)
        }
    } else if providerCfg.Disabled || providerCfg.APIKey == "" {
        // Provider 被禁用或没有 API Key
        logging.Warn("provider is disabled or has no API key, reverting to default", ...)
        // 回退到其他 Provider
    }
    
    // 3. 验证 MaxTokens
    if agent.MaxTokens <= 0 {
        updatedAgent := cfg.Agents[name]
        if model.DefaultMaxTokens > 0 {
            updatedAgent.MaxTokens = model.DefaultMaxTokens
        } else {
            updatedAgent.MaxTokens = MaxTokensFallbackDefault  // 4096
        }
        cfg.Agents[name] = updatedAgent
    } else if model.ContextWindow > 0 && agent.MaxTokens > model.ContextWindow/2 {
        // MaxTokens 不应超过上下文窗口的一半
        updatedAgent := cfg.Agents[name]
        updatedAgent.MaxTokens = model.ContextWindow / 2
        cfg.Agents[name] = updatedAgent
    }
    
    // 4. 验证 Reasoning Effort
    if model.CanReason {
        if agent.ReasoningEffort == "" {
            updatedAgent := cfg.Agents[name]
            updatedAgent.ReasoningEffort = "medium"
            cfg.Agents[name] = updatedAgent
        }
    }
    
    return nil
}

六、上下文路径

6.1 上下文路径列表

OpenCode 支持多种上下文文件，用于在会话开始时注入额外的上下文：

var defaultContextPaths = []string{
    ".github/copilot-instructions.md",  // GitHub Copilot 兼容
    ".cursorrules",                     // Cursor 规则
    ".cursor/rules/",                   // Cursor 规则目录
    "CLAUDE.md",                        // Claude 通用
    "CLAUDE.local.md",                  // 本地 Claude 配置
    "opencode.md",                      // OpenCode 通用
    "opencode.local.md",               // 本地 OpenCode 配置
    "OpenCode.md",                      // 大写变体
    "OpenCode.local.md",
    "OPENCODE.md",
    "OPENCODE.local.md",
}

6.2 上下文文件用途

这些上下文文件通常用于：

项目说明：描述项目架构、技术栈
编码规范：代码风格、命名约定
特殊指令：禁止或限制某些操作
工作流程：推荐的开发步骤

6.3 上下文文件加载

当创建新会话时，OpenCode 会：

检查工作目录是否存在上述文件
按顺序读取内容
将内容合并作为 system prompt 的一部分

七、配置文件示例

7.1 最小配置

// ~/.opencode.json 或项目目录 .opencode.json
{
}

仅配置 API Key，其他使用默认值：

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  }
}

7.2 完整配置示例

{
  "$schema": "./opencode-schema.json",
  
  "data": {
    "directory": ".opencode"
  },
  
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "openai": {
      "apiKey": "sk-..."
    }
  },
  
  "agents": {
    "coder": {
      "model": "claude-4-sonnet-20250514",
      "maxTokens": 8192
    },
    "summarizer": {
      "model": "claude-4-sonnet-20250514",
      "maxTokens": 4096
    }
  },
  
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  },
  
  "lsp": {
    "gopls": {
      "command": "gopls"
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  },
  
  "contextPaths": [
    "CLAUDE.md",
    "opencode.md"
  ],
  
  "tui": {
    "theme": "dracula"
  },
  
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  },
  
  "autoCompact": true,
  "debug": false
}

7.3 项目本地配置

// 项目根目录 .opencode.json
{
  "$schema": "./opencode-schema.json",
  "lsp": {
    "gopls": {
      "command": "gopls"
    }
  }
}

八、环境变量参考

8.1 Provider API Keys

环境变量	Provider
`ANTHROPIC_API_KEY`	Anthropic (Claude)
`OPENAI_API_KEY`	OpenAI
`GEMINI_API_KEY`	Google Gemini
`GROQ_API_KEY`	Groq
`OPENROUTER_API_KEY`	OpenRouter
`XAI_API_KEY`	xAI (Grok)
`AZURE_OPENAI_API_KEY`	Azure OpenAI
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI Endpoint

8.2 AWS 相关

环境变量	用途
`AWS_ACCESS_KEY_ID`	AWS 访问密钥
`AWS_SECRET_ACCESS_KEY`	AWS 秘密密钥
`AWS_PROFILE`	AWS Profile 名称
`AWS_REGION`	AWS 区域
`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`	ECS 容器凭证

8.3 Google Cloud

环境变量	用途
`VERTEXAI_PROJECT`	Vertex AI 项目
`VERTEXAI_LOCATION`	Vertex AI 区域
`GOOGLE_CLOUD_PROJECT`	GCP 项目
`GOOGLE_CLOUD_REGION`	GCP 区域

8.4 开发调试

环境变量	用途
`OPENCODE_DEV_DEBUG`	启用调试模式，写入 debug.log
`DEBUG`	通用调试标志

九、调试功能

9.1 调试模式

if os.Getenv("OPENCODE_DEV_DEBUG") == "true" {
    loggingFile := fmt.Sprintf("%s/%s", cfg.Data.Directory, "debug.log")
    messagesPath := fmt.Sprintf("%s/%s", cfg.Data.Directory, "messages")
    
    // 创建日志文件
    sloggingFileWriter, _ := os.OpenFile(loggingFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o666)
    
    logger := slog.New(slog.NewTextHandler(sloggingFileWriter, &slog.HandlerOptions{
        Level: defaultLevel,
    }))
    slog.SetDefault(logger)
}

9.2 消息目录

在调试模式下，OpenCode 还会保存完整的消息历史：

.opencode/
├── opencode.db           # SQLite 数据库
├── debug.log             # 调试日志
└── messages/             # 消息历史
    ├── msg_001.json
    ├── msg_002.json
    └── ...

十、设计哲学

10.1 渐进式配置

OpenCode 追求"零配置启动"——用户可以完全不配置任何东西，直接运行 opencode 命令。系统会自动：

检测可用的 API Key
选择合适的默认模型
使用内置的默认值

10.2 灵活性优先

虽然默认值已经很合理，但用户可以通过配置完全自定义：

更换默认模型
配置多个 Provider
添加 MCP 服务器
设置自定义 LSP

10.3 安全性

敏感信息（API Keys）建议通过环境变量提供，而不是写入配置文件：

export ANTHROPIC_API_KEY="sk-ant-..."
opencode

结语

OpenCode 的配置系统体现了几个重要原则：

零配置启动：用户无需配置即可使用
渐进式复杂度：从简单使用到深度定制
环境变量优先：敏感信息通过环境变量提供
智能回退：Provider/模型不可用时自动回退

这套配置系统让 OpenCode 既适合新手快速上手，也满足高级用户的个性化需求。

本系列下一篇文章将深入探讨 OpenCode 的 LSP（Language Server Protocol）集成，解析如何获取代码结构、符号定义、悬停文档等信息。