配置系统详解

目标：理解 OpenCode 的多层配置体系，灵活管理不同场景

概述

OpenCode 的配置系统采用多层合并策略，让你可以在组织、个人、项目、环境变量等多个层级管理设置。理解这套体系，是高效使用 OpenCode 的基础。

配置格式

OpenCode 支持两种格式：

格式	文件扩展名	特点	适用场景
JSON	`opencode.json`	标准 JSON，无注释	机器生成、CI/CD
JSONC	`opencode.jsonc`	带注释的 JSON	推荐日常使用

为什么推荐 JSONC？

{
  "$schema": "https://opencode.ai/config.json",
  // 使用的模型——日常主力
  "model": "anthropic/claude-sonnet-4-5",
  // 自动更新——保持最新功能
  "autoupdate": true,
  // 服务器配置——Web 界面端口
  "server": {
    "port": 4096
  }
}

$schema 字段提供 IDE 自动补全和校验。VS Code 等编辑器会自动识别 schema 并给出提示。

配置优先级（重要！）

OpenCode 的配置是合并而非替换，优先级从低到高：

核心规则：后面的覆盖前面的（仅冲突键），非冲突键全部保留。

配置合并可视化

合并规则详解

非冲突键：全部保留
冲突键：后面的覆盖前面的

示例：

全局配置：

{ "autoupdate": true, "theme": "dark" }

项目配置：

{ "model": "gpt-4o", "theme": "light" }

最终配置：

{ "autoupdate": true, "theme": "light", "model": "gpt-4o" }

各层配置详解

1. 远程配置

组织可通过 .well-known/opencode 端点提供默认配置：

https://your-org.com/.well-known/opencode

用途：

统一团队模型选择
预配置 MCP 服务器
设置安全策略
强制代码规范

示例响应：

{
  "model": "anthropic/claude-sonnet-4-5",
  "mcp": {
    "github": { "enabled": false }
  },
  "rules": [
    "使用 TypeScript 严格模式",
    "所有 API 需要单元测试"
  ]
}

真实场景案例 ①：企业统一管控

某 50 人技术团队通过远程配置强制所有项目使用同一个模型和规则集，确保代码风格一致，同时禁用未经授权的 MCP 服务器，降低安全风险。

2. 全局配置

位置：

~/.config/opencode/opencode.json

用途：个人偏好设置

{
  "model": "anthropic/claude-sonnet-4-5",
  "theme": "opencode",
  "autoupdate": true,
  "permission": {
    "bash": "ask"
  },
  "server": {
    "port": 4096
  }
}

3. 环境变量

# 指定配置文件路径
export OPENCODE_CONFIG=/path/to/custom-config.json
 
# 直接传入配置内容（最高优先级）
export OPENCODE_CONFIG_CONTENT='{"model":"gpt-4o"}'

4. 项目配置

位置：项目根目录的 opencode.json

{
  "model": "deepseek/deepseek-chat",
  "formatters": {
    "*.ts": "prettier --write",
    "*.rs": "rustfmt"
  },
  "rules": [
    "使用 TypeScript 严格模式",
    "所有 API 路由需要认证",
    "数据库操作使用事务"
  ]
}

务必加入 Git：

git add opencode.json
git commit -m "Add OpenCode config"

真实场景案例 ②：前后端项目差异化配置

前端项目 opencode.json 配置 formatters 为 prettier，规则要求使用 React Hooks；后端项目配置 formatters 为 gofmt，规则要求所有 Handler 必须包含错误处理。同一个开发者切换项目时，OpenCode 自动适配。

5. .opencode 目录

项目或全局的 .opencode/ 目录存放：

.opencode/
├── agents/        # 自定义代理
├── commands/      # 自定义命令
├── modes/         # 自定义模式
├── plugins/       # 插件
├── skills/        # 代理技能
├── tools/         # 自定义工具
└── themes/        # 自定义主题

全局位置：~/.config/opencode/

6. 内联配置

临时覆盖，用于脚本或 CI：

# 单次运行使用轻量模型
OPENCODE_CONFIG_CONTENT='{"model":"gpt-4o-mini"}' opencode
 
# CI 流水线中禁用交互式确认
OPENCODE_CONFIG_CONTENT='{"permission":{"bash":"allow"}}' opencode

真实场景案例 ③：CI/CD 流水线

在 GitHub Actions 中，通过 OPENCODE_CONFIG_CONTENT 传入只读权限配置，确保 AI 在自动化审查中不会意外修改代码：
- name: AI Code Review
  run: opencode review
  env:
    OPENCODE_CONFIG_CONTENT: '{"permission":{"edit":"deny","bash":"deny"}}'

多环境配置实战

开发大型项目时，不同环境需要不同的 AI 行为：

环境切换脚本示例

#!/bin/bash
# scripts/opencode-env.sh
 
ENV=${1:-dev}
 
case $ENV in
  dev)
    export OPENCODE_CONFIG_CONTENT='{"model":"gpt-4o-mini","permission":{"bash":"ask"}}'
    echo "✅ 已切换到开发模式（轻量模型 + 安全确认）"
    ;;
  staging)
    export OPENCODE_CONFIG_CONTENT='{"model":"anthropic/claude-sonnet-4-5","permission":{"edit":"deny"}}'
    echo "✅ 已切换到测试模式（标准模型 + 只读）"
    ;;
  prod)
    export OPENCODE_CONFIG_CONTENT='{"model":"anthropic/claude-opus-4","permission":{"bash":"deny","edit":"deny"}}'
    echo "✅ 已切换到生产模式（最强模型 + 只读）"
    ;;
  *)
    echo "用法: $0 {dev|staging|prod}"
    exit 1
    ;;
esac

JSONC 完整配置模板

{
  "$schema": "https://opencode.ai/config.json",
 
  // ═══════════════════════════════════════
  // 模型配置
  // ═══════════════════════════════════════
  "model": "anthropic/claude-sonnet-4-5",
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "plan": "anthropic/claude-opus-4",
    "code": "deepseek/deepseek-chat"
  },
  "fallback": ["deepseek/deepseek-chat", "openai/gpt-4o"],
 
  // ═══════════════════════════════════════
  // 提供商配置
  // ═══════════════════════════════════════
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com"
      }
    },
    "deepseek": {
      "options": {
        "baseURL": "https://api.deepseek.com/v1"
      }
    }
  },
 
  // ═══════════════════════════════════════
  // 权限控制
  // ═══════════════════════════════════════
  "permission": {
    "edit": "ask",        // 编辑前确认
    "bash": "ask",        // 命令前确认
    "webfetch": "allow",  // 允许联网
    "mcp_*": "ask"        // MCP 工具统一确认
  },
 
  // ═══════════════════════════════════════
  // MCP 服务器
  // ═══════════════════════════════════════
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "enabled": true
    }
  },
 
  // ═══════════════════════════════════════
  // 规则
  // ═══════════════════════════════════════
  "rules": [
    "使用 TypeScript 严格模式",
    "所有 API 路由需要认证",
    "数据库操作使用事务",
    "优先使用 async/await 而非回调"
  ],
 
  // ═══════════════════════════════════════
  // 格式化
  // ═══════════════════════════════════════
  "formatters": {
    "*.ts": "prettier --write",
    "*.json": "prettier --write",
    "*.md": "prettier --write"
  },
 
  // ═══════════════════════════════════════
  // 服务器（Web 界面）
  // ═══════════════════════════════════════
  "server": {
    "port": 4096,
    "host": "127.0.0.1"
  },
 
  // ═══════════════════════════════════════
  // 其他
  // ═══════════════════════════════════════
  "theme": "opencode",
  "autoupdate": true,
  "telemetry": false
}

常用配置项速查

模型配置

{
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://custom-api.example.com"
      }
    }
  }
}

权限控制

{
  "permission": {
    "edit": "allow",     // 自动编辑文件
    "bash": "ask",       // 运行命令前询问
    "webfetch": "deny"   // 禁止获取网页
  }
}

MCP 服务器

{
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

规则

{
  "rules": [
    "使用 TypeScript 严格模式",
    "所有 API 路由需要认证",
    "数据库操作使用事务"
  ]
}

FAQ

Q: 项目配置和全局配置冲突时，哪个生效？

A: 项目配置优先级更高，会覆盖全局配置中的冲突键。非冲突键两者都会保留。

Q: 如何查看当前生效的完整配置？

A: 在 TUI 中输入 /config，或查看合并后的配置文件：
cat ~/.config/opencode/opencode.json

Q: 可以在一个项目里同时用 opencode.json 和 opencode.jsonc 吗？

A: 不建议。OpenCode 只会读取其中一个，通常优先读取 .jsonc。请只保留一种格式避免混淆。

Q: 环境变量覆盖配置时，需要重启 OpenCode 吗？

A: 不需要。OPENCODE_CONFIG_CONTENT 在每次启动时读取，只需重新运行命令即可生效。

避坑清单 ⚠️

坑	后果	正确做法
在配置中硬编码 API 密钥	密钥泄露到 Git 历史	使用 `${ENV_VAR}` 或 `.env` 文件
同时存在 `opencode.json` 和 `opencode.jsonc`	配置行为不可预期	只保留一种格式
项目配置忘记 `git add`	团队成员配置不一致	将 `opencode.json` 纳入版本控制
远程配置返回无效 JSON	OpenCode 启动失败	先本地验证 JSON 格式
规则过多（>20 条）	AI 忽略部分规则	保持 10-15 条核心规则
生产环境 `bash: allow`	AI 可能执行危险命令	生产环境始终使用 `ask` 或 `deny`

练习

在你的项目创建 opencode.json，设置一个规则
在全局配置设置默认权限
用环境变量临时切换模型
编写一个多环境切换脚本

下一篇：09. 模型选择与切换