2.1 配置文件详解

OpenCode使用JSON/JSONC格式的配置文件，支持多层级配置合并，让你可以灵活地管理全局和项目级别的设置。

配置文件格式

OpenCode接受JSON和JSONC（JSON with Comments）两种格式。配置文件可以包含$schema引用以获得编辑器智能提示：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "theme": "tokyonight"
}

配置文件位置与优先级

OpenCode按以下顺序查找和合并配置文件（后面的覆盖前面的）：

优先级	位置	说明
1（最低）	.well-known/opencode	远程配置
2	~/.config/opencode/opencode.json	全局配置
3	OPENCODE_CONFIG 环境变量	自定义配置路径
4	项目根目录 opencode.json	项目配置
5	.opencode 目录	项目配置目录
6（最高）	OPENCODE_CONFIG_CONTENT 环境变量	内联配置

核心配置项

模型与提供商

{
  // 主要使用的LLM模型
  "model": "anthropic/claude-sonnet-4-20250514",

  // 用于轻量任务的小模型
  "small_model": "anthropic/claude-haiku-3-5",

  // 提供商特定选项
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

界面设置

{
  // 主题选择
  "theme": "tokyonight",

  // TUI界面选项
  "tui": {
    "scroll_speed": 3,
    "diff_style": "unified"
  },

  // 服务器配置
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  }
}

工具配置

{
  // 启用/禁用特定工具
  "tools": {
    "bash": true,
    "write": true,
    "edit": true,
    "webfetch": true
  }
}

代理配置

{
  // 自定义代理
  "agent": {
    "review": {
      "description": "代码审查专家",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "tools": {
        "write": false,
        "bash": false
      }
    }
  },

  // 默认代理
  "default_agent": "build"
}

命令配置

{
  // 自定义命令
  "command": {
    "test": {
      "template": "运行项目的测试套件并报告结果",
      "description": "运行测试"
    },
    "review": {
      "template": "审查 $ARGUMENTS 中的代码更改",
      "description": "代码审查"
    }
  }
}

快捷键配置

{
  // 自定义快捷键
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c",
    "session_new": "n",
    "model_list": "m"
  }
}

高级配置

MCP服务器

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

格式化器

{
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

权限配置

{
  "permission": {
    "bash": "ask",
    "edit": "allow",
    "read": "allow",
    "webfetch": "ask"
  }
}

其他配置

{
  // 自动更新设置
  "autoupdate": true,  // true | false | "notify"

  // 分享设置
  "share": "manual",  // "manual" | "auto" | "disabled"

  // 上下文压缩
  "compaction": {
    "enabled": true
  },

  // 文件监视忽略
  "watcher": {
    "ignore": ["node_modules", ".git", "dist"]
  },

  // 指令文件路径
  "instructions": ["docs/guidelines.md", "AGENTS.md"]
}

变量替换

配置文件支持变量替换：

环境变量

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

文件内容

{
  "instructions": ["{file:./prompts/system.md}"]
}

配置示例

完整的全局配置示例

{
  "$schema": "https://opencode.ai/config.json",

  // 模型配置
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-3-5",

  // 界面配置
  "theme": "tokyonight",
  "tui": {
    "scroll_speed": 3
  },

  // 工具权限
  "permission": {
    "bash": "ask",
    "edit": "allow",
    "read": "allow"
  },

  // 自定义命令
  "command": {
    "commit": {
      "template": "查看git diff并生成commit message",
      "description": "生成commit message"
    }
  },

  // 快捷键
  "keybinds": {
    "leader": "ctrl+x"
  },

  // 自动更新
  "autoupdate": "notify"
}

下一步

了解配置文件结构后，接下来让我们详细了解如何配置AI提供商。