【OpenCode系统性指南】第5篇：配置文件详解：打造专属开发环境

引言

默认配置只能让你「用起来」，而个性化配置才能让你「用得爽」。OpenCode 的配置系统既强大又灵活——从模型选择到快捷键，从权限控制到工具开关，几乎所有行为都可以定制。本文将带你深入理解 opencode.json 的每个核心配置项，掌握配置优先级规则，并分享一套实用的配置方案。

---

一、opencode.json 核心配置项

OpenCode 的配置文件采用 JSON 格式，通常命名为 opencode.json。一个完整的配置文件结构如下：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "theme": "opencode",
  "autoupdate": true,
  "default_agent": "build",
  "provider": {},
  "permission": {},
  "keybinds": {},
  "tui": {},
  "tools": {},
  "agent": {},
  "command": {},
  "mcp": {},
  "plugin": [],
  "instructions": [],
  "formatter": {}
}

1.1 模型配置

模型配置是整个系统的核心，决定了 AI 的「大脑」是谁。

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

• model：主模型，处理复杂任务（代码生成、重构、架构设计等）
• small_model：轻量模型，处理简单任务（自动补全、快速问答等）

选择 small_model 的好处是节省成本和提升响应速度。比如在日常开发中，大量的简单查询可以交给 Haiku，而复杂的代码审查才动用 Sonnet。

1.2 主题配置

OpenCode 内置了多款主题，也支持自定义主题文件。

{
  "theme": "opencode"
}

内置主题包括：opencode（默认）、dracula、nord、gruvbox、tokyonight 等。你也可以通过 --theme 命令行参数临时切换，或在配置中指定自定义主题文件路径。

1.3 快捷键配置

快捷键配置让你用键盘掌控一切。OpenCode 采用 Leader 键 机制，默认 Leader 键是 ctrl+x。

{
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "theme_list": "<leader>t",
    "model_list": "<leader>m",
    "session_new": "<leader>n",
    "session_list": "<leader>l"
  }
}

常用快捷键说明：

• <leader>t - 切换主题
• <leader>m - 切换模型
• <leader>n - 新建会话
• <leader>l - 查看会话列表

1.4 权限配置

权限控制系统决定 AI 能做什么、不能做什么。有三种模式：allow（允许）、ask（询问）、deny（禁止）。

{
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": {
      "*": "ask",
      "src/**": "allow"
    },
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  }
}

这个配置的含义是：

• 默认所有操作都「询问」用户
• 允许所有 bash 命令（后面会细化）
• 编辑 src/** 目录下的文件直接允许
• git 和 npm 命令直接允许
• 禁止所有 rm 删除命令

1.5 工具配置

OpenCode 内置了多种工具，你可以按需开启或关闭。

{
  "tools": {
    "bash": true,
    "edit": true,
    "glob": true,
    "grep": true,
    "read": true,
    "write": true,
    "web_search": false
  }
}

如果你工作在离线环境，可以关闭 web_search；如果担心文件被误删，可以关闭 write。

---

二、配置文件的优先级规则

当你同时在多个地方配置了 OpenCode，系统如何决定使用哪个配置？这就涉及到优先级规则。

2.1 六层优先级（从低到高）

2.2 合并机制

关键点：配置采用「合并」而非「替换」机制。这意味着：

• 低层级配置的 A 选项，高层级配置的 B 选项，最终 A 和 B 都生效
• 只有当相同的键冲突时，高层级才会覆盖低层级

举个例子：

// 全局配置
{
  "theme": "opencode",
  "model": "claude-sonnet-4-5",
  "permission": { "bash": "allow" }
}

// 项目配置
{
  "model": "claude-opus-4-5",
  "permission": { "edit": "ask" }
}

// 最终合并结果
{
  "theme": "opencode",           // 来自全局配置
  "model": "claude-opus-4-5",    // 项目配置覆盖
  "permission": {
    "bash": "allow",             // 来自全局配置
    "edit": "ask"                // 来自项目配置
  }
}

2.3 配置文件位置

不同操作系统的配置目录略有不同：

• Linux/macOS：~/.config/opencode/opencode.json
• Windows：%APPDATA%\opencode\opencode.json
• 项目级：项目根目录的 opencode.json

---

三、我的配置文件分享

下面是我日常使用的配置文件，兼顾效率与安全：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "theme": "tokyonight",
  "autoupdate": true,
  "default_agent": "build",

  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  },

  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "git log": "allow",
      "npm run *": "allow",
      "pnpm *": "allow"
    },
    "edit": {
      "src/**": "allow",
      "tests/**": "allow",
      "*.md": "allow"
    },
    "write": {
      "src/**": "allow"
    }
  },

  "keybinds": {
    "leader": "ctrl+x",
    "theme_list": "<leader>t",
    "model_list": "<leader>m",
    "session_new": "<leader>n"
  },

  "tui": {
    "scroll_speed": 3,
    "diff_style": "auto"
  },

  "tools": {
    "bash": true,
    "edit": true,
    "read": true,
    "glob": true,
    "grep": true,
    "web_search": true
  },

  "instructions": [
    ".claude/CLAUDE.md"
  ]
}

配置亮点解读

1. 双模型策略：Sonnet 处理复杂任务，Haiku 处理简单任务，平衡成本与效果
2. 细粒度权限：只读的 git 命令直接放行，编辑操作按目录白名单
3. TUI 优化：设置合适的滚动速度，diff 样式自动适配
4. 指令文件：引入项目的 CLAUDE.md，让 AI 理解项目规范

---

四、环境变量配置技巧

除了 JSON 配置文件，OpenCode 还支持通过环境变量进行灵活配置。这在 CI/CD、容器化部署等场景特别有用。

4.1 配置路径环境变量

# 指定自定义配置文件路径
export OPENCODE_CONFIG="/path/to/custom-config.json"

# 指定配置目录
export OPENCODE_CONFIG_DIR="/custom/config/dir"

# 运行时内联配置（最高优先级）
export OPENCODE_CONFIG_CONTENT='{"model": "claude-opus-4-5"}'

4.2 变量替换语法

在 JSON 配置中，你可以引用环境变量或文件内容：

{
  "model": "{env:OPENCODE_MODEL}",

  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

这种方式的优点是：

• 安全：敏感信息（API Key）不用写进配置文件
• 灵活：不同环境使用不同的环境变量值
• 版本控制友好：配置文件可以安全提交到 Git

4.3 Shell 配置示例

在 ~/.bashrc 或 ~/.zshrc 中添加：

# OpenCode 环境变量
export OPENCODE_MODEL="anthropic/claude-sonnet-4-5"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 或者从文件读取
export ANTHROPIC_API_KEY=$(cat ~/.secrets/anthropic-key)

4.4 项目级 .env 文件

对于团队项目，推荐使用 .env 文件（记得加入 .gitignore）：

# .env
OPENCODE_MODEL=anthropic/claude-sonnet-4-5
ANTHROPIC_API_KEY=sk-ant-xxxxx

然后在启动 OpenCode 前加载：

source .env && opencode

---

小结

• 核心配置项：model/small_model 决定 AI 大脑，permission 控制行为边界，keybinds 提升操作效率
• 优先级规则：6 层配置从低到高，采用「合并」机制，仅键冲突时覆盖
• 环境变量：用于敏感信息保护和多环境切换，支持 {env:} 和 {file:} 两种替换语法
• 最佳实践：全局配置放通用设置，项目配置放特定需求，敏感信息用环境变量

延伸阅读

• 配置 (Config) - OpenCode 官方文档
• 权限 (Permissions) 详解
• 快捷键 (Keybinds) 完整列表
• 模型 (Models) 选择指南
• 提供商 (Providers) 配置