配置文件详解

理解 Opencode 的配置体系是进阶使用的关键。本文将详细讲解配置文件的位置、优先级规则以及核心配置项。

配置文件位置

Opencode 支持两个层级的配置：

配置文件位置作用范围
全局配置~/.config/opencode/opencode.json所有项目
项目配置./opencode.json 或 ./.opencode/opencode.json当前项目

Windows 用户注意：全局配置位于 %USERPROFILE%\.config\opencode\opencode.json

配置格式：JSONC

Opencode 支持 JSONC 格式（JSON with Comments），你可以在配置文件中添加注释：

{
  "$schema": "https://opencode.ai/config.json",
  
  // 主题配置
  "theme": "opencode-dark",
  
  /* 主模型设置 */
  "model": "anthropic/claude-sonnet-4-5",
  
  // 自动更新
  "autoupdate": true
}

配置优先级

当存在多个配置文件时，Opencode 按以下优先级合并配置（从低到高）：

  1. 远程组织配置 - .well-known/opencode（最低）
  2. 全局配置 - ~/.config/opencode/opencode.json
  3. 环境变量配置 - OPENCODE_CONFIG 环境变量
  4. 项目配置 - ./opencode.json
  5. 项目目录配置 - ./.opencode/
  6. 运行时配置 - OPENCODE_CONFIG_CONTENT 环境变量（最高）

重要：配置是合并而非替换。后面的配置只会覆盖冲突的字段。

示例

假设全局配置：

{
  "model": "anthropic/claude-sonnet-4-5",
  "theme": "dark",
  "autoupdate": true
}

项目配置：

{
  "model": "deepseek/deepseek-coder"
}

最终生效的配置：

{
  "model": "deepseek/deepseek-coder",  // 被项目配置覆盖
  "theme": "dark",                      // 继承全局配置
  "autoupdate": true                    // 继承全局配置
}

核心配置项

1. 模型配置

{
  // 主模型（用于复杂任务）
  "model": "anthropic/claude-sonnet-4-5",
  
  // 小模型（用于简单任务，如生成标题）
  "small_model": "anthropic/claude-haiku-4-5",
  
  // 启用的 Provider
  "enabled_providers": ["anthropic", "openai"],
  
  // 禁用的 Provider（优先级更高）
  "disabled_providers": ["ollama"]
}

2. Provider 配置

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,      // 请求超时（毫秒）
        "setCacheKey": true     // 启用缓存
      }
    },
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.deepseek.com/v1",
        "apiKey": "{env:DEEPSEEK_API_KEY}"  // 从环境变量读取
      }
    }
  }
}

3. 权限配置

{
  "permission": {
    // 文件读取权限
    "read": {
      "*": "allow",                    // 默认允许
      "*.env": "deny",                 // 禁止读取 .env
      "*.env.*": "deny",               // 禁止读取 .env.local 等
      "*.env.example": "allow"         // 允许读取示例文件
    },
    
    // 文件编辑权限
    "edit": "ask",                     // 修改前询问
    
    // 命令执行权限
    "bash": {
      "*": "ask",                      // 默认询问
      "git status": "allow",           // 安全命令直接放行
      "git diff": "allow",
      "npm test": "allow",
      "rm -rf": "deny"                 // 危险命令禁止
    }
  }
}

权限值说明：

  • "allow" - 直接放行
  • "ask" - 每次询问
  • "deny" - 直接拒绝

4. 文件监控配置

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

性能提示：大型项目务必配置 ignore，避免 CPU 占用过高。

5. 上下文压缩配置

{
  "compaction": {
    "auto": true,      // 上下文满时自动压缩
    "prune": true      // 删除旧的工具输出节省 token
  }
}

6. TUI 界面配置

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"  // 或 "stacked"
  }
}

7. Agent 配置

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是代码审查专家，关注安全、性能和可维护性。",
      "tools": {
        "write": false,   // 禁止修改文件
        "edit": false     // 禁止编辑
      }
    }
  },
  "default_agent": "plan"  // 默认使用的 Agent
}

8. 变量替换

配置文件支持变量引用：

{
  // 从环境变量读取
  "model": "{env:OPENCODE_MODEL}",
  
  // 从文件读取
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

实用配置模板

最小化配置

适合快速开始：

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

生产级配置

适合团队协作：

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

隐私优先配置

完全使用本地模型：

{
  "model": "ollama/deepseek-coder",
  "enabled_providers": ["ollama"],
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "deepseek-coder": {
          "name": "DeepSeek Coder",
          "contextWindow": 16384
        }
      }
    }
  }
}

配置验证

检查配置是否生效

# 查看当前使用的模型
opencode config get model

# 查看所有配置
opencode config list

# 验证配置文件语法
opencode config validate

调试配置问题

如果配置不生效，按以下步骤排查：

  1. 检查 JSON 语法：使用在线工具验证 JSON 格式
  2. 查看日志：~/.config/opencode/logs/ 目录
  3. 使用 JSONC：如果需要注释，确保文件后缀是 .jsonc
  4. 检查权限：确保配置文件可读

常见问题

Q: 配置修改后需要重启吗？

大部分配置会自动生效，但 Provider 和插件配置需要重启 Opencode。

Q: 如何重置配置？

删除配置文件后重启：

rm ~/.config/opencode/opencode.json

Q: 团队如何共享配置？

将项目配置 opencode.json 提交到 Git，团队成员克隆后自动生效。敏感信息（如 API Key）使用环境变量。

下一步

本文由 OpenCodex 社区整理，欢迎贡献更多配置技巧。

最近更新: