OpenCode 配置完全指南：从入门到精通
作为一款强大的 AI 编程助手，OpenCode 提供了灵活的配置系统，让你能够根据自己的需求定制工作环境。无论你是刚接触 OpenCode 的新手，还是希望深度定制的老用户，这篇指南都会帮你快速上手配置。
配置文件基础
支持的格式
OpenCode 支持两种配置文件格式：
- JSON：标准的 JSON 格式
- JSONC：支持注释的 JSON 格式（推荐使用）
一个基本的配置文件看起来是这样的：
{
"$schema": "https://opencode.ai/config.json",
// 主题配置
"theme": "opencode",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true
}
$schema 字段让你的编辑器能够提供自动补全和校验功能，强烈建议保留。
配置文件的位置与优先级
OpenCode 会从多个位置读取配置，这些配置会合并在一起，而不是简单替换。当同一个配置项出现在多个位置时，后加载的配置会覆盖先加载的。
加载顺序（从低到高）
- 远程配置：通过
.well-known/opencode端点获取的组织级默认配置 - 全局配置：
~/.config/opencode/opencode.json，存放个人偏好 - 自定义配置：通过
OPENCODE_CONFIG环境变量指定的配置文件 - 项目配置：项目根目录下的
opencode.json，存放项目特定设置 - .opencode 目录：存放 agents、commands、plugins 等扩展配置
- 内联配置：通过
OPENCODE_CONFIG_CONTENT环境变量传入的运行时配置
举个例子，假设你的全局配置设置了 theme: "opencode" 和 autoupdate: true，项目配置设置了 model: "anthropic/claude-sonnet-4-5"，最终生效的配置会包含这三个设置。
全局配置
全局配置位于 ~/.config/opencode/opencode.json，适合存放用户级别的偏好设置，比如主题、按键绑定等。
项目配置
在项目根目录创建 opencode.json 文件即可。OpenCode 启动时会从当前目录向上查找，直到找到最近的 Git 目录。项目配置可以安全地提交到版本控制系统。
自定义配置路径
如果你需要使用自定义位置的配置文件：
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"
也可以指定配置目录：
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
核心配置项详解
模型配置
通过 provider、model 和 small_model 配置使用的 AI 模型：
{
"$schema": "https://opencode.ai/config.json",
"provider": {},
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}
small_model 用于标题生成等轻量任务，默认会自动选择较便宜的模型。
Provider 高级选项
{
"provider": {
"anthropic": {
"options": {
"timeout": 600000,
"setCacheKey": true
}
}
}
}
timeout：请求超时时间（毫秒），默认 300000，设为false可禁用setCacheKey：确保始终设置缓存键
Amazon Bedrock 配置
如果你使用 AWS Bedrock，可以这样配置：
{
"provider": {
"amazon-bedrock": {
"options": {
"region": "us-east-1",
"profile": "my-aws-profile",
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
}
}
}
}
工具配置
控制 AI 可以使用哪些工具：
{
"tools": {
"write": false,
"bash": false
}
}
这个配置会禁用文件写入和命令执行功能，适合只需要代码审查的场景。
权限配置
默认情况下，OpenCode 允许所有操作。如果你希望某些操作需要确认：
{
"permission": {
"edit": "ask",
"bash": "ask"
}
}
设为 "ask" 后，执行这些操作前会先询问用户确认。
主题配置
通过 theme 选项自定义界面外观：
{
"theme": "opencode"
}
你也可以在 ~/.config/opencode/themes/ 或 .opencode/themes/ 目录下创建自定义主题。
TUI 界面配置
针对终端界面的配置项：
{
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
}
}
scroll_acceleration.enabled：启用 macOS 风格的滚动加速scroll_speed：滚动速度倍数（默认 3，最小 1）diff_style：差异显示风格，"auto"会根据终端宽度自适应，"stacked"始终单列显示
服务器配置
配置 opencode serve 和 opencode web 命令的服务器选项：
{
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true,
"mdnsDomain": "myproject.local",
"cors": ["http://localhost:5173"]
}
}
port：监听端口hostname：监听主机名mdns：启用 mDNS 服务发现，方便局域网内其他设备访问mdnsDomain：自定义 mDNS 域名cors：配置 CORS 允许的来源
自定义 Agent
通过配置创建专门用途的 Agent：
{
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices and potential issues",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
"tools": {
// 禁用文件修改工具，只做审查
"write": false,
"edit": false
}
}
}
}
也可以在 ~/.config/opencode/agents/ 或 .opencode/agents/ 目录下用 Markdown 文件定义 Agent。
设置默认 Agent
{
"default_agent": "plan"
}
默认 Agent 必须是主 Agent（非子 Agent），可以是内置的 "build"、"plan"，或你自定义的 Agent。
自定义命令
为重复性任务创建快捷命令：
{
"command": {
"test": {
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
"description": "Run tests with coverage",
"agent": "build",
"model": "anthropic/claude-haiku-4-5"
},
"component": {
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
"description": "Create a new component"
}
}
}
命令也可以通过 Markdown 文件定义。
MCP 服务器配置
集成 MCP（Model Context Protocol）服务器：
{
"mcp": {}
}
组织可以通过远程配置提供默认禁用的 MCP 服务器，你可以在本地配置中启用：
{
"mcp": {
"jira": {
"type": "remote",
"url": "https://jira.example.com/mcp",
"enabled": true
}
}
}
代码格式化配置
配置代码格式化工具：
{
"formatter": {
"prettier": {
"disabled": true
},
"custom-prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
}
}
}
上下文压缩配置
控制会话上下文的压缩行为：
{
"compaction": {
"auto": true,
"prune": true
}
}
auto：上下文满时自动压缩（默认 true）prune：移除旧的工具输出以节省 token（默认 true）
文件监视器配置
配置需要忽略的文件路径：
{
"watcher": {
"ignore": [
"node_modules/**",
"dist/**",
".git/**"
]
}
}
分享功能配置
{
"share": "manual"
}
可选值：
"manual"：手动通过/share命令分享（默认）"auto"：自动分享新对话"disabled"：完全禁用分享
插件配置
从 npm 加载插件：
{
"plugin": [
"opencode-helicone-session",
"@my-org/custom-plugin"
]
}
也可以在 .opencode/plugins/ 或 ~/.config/opencode/plugins/ 目录下放置插件文件。
指令文件配置
指定额外的指令文件：
{
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
".cursor/rules/*.md"
]
}
支持 glob 模式匹配多个文件。
Provider 管理
禁用特定 Provider
{
"disabled_providers": ["openai", "gemini"]
}
被禁用的 Provider 即使设置了环境变量或 API Key 也不会加载。
启用特定 Provider
{
"enabled_providers": ["anthropic", "openai"]
}
只启用指定的 Provider，其他全部忽略。
需要注意的是，disabled_providers 的优先级高于 enabled_providers。
自动更新配置
{
"autoupdate": false
}
设为 false 禁用自动更新，设为 "notify" 只通知有新版本但不自动下载。
变量替换
配置文件支持变量替换，让配置更灵活。
环境变量
使用 {env:VARIABLE_NAME} 语法：
{
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}
文件内容
使用 {file:path/to/file} 语法：
{
"provider": {
"openai": {
"options": {
"apiKey": "{file:~/.secrets/openai-key}"
}
}
}
}
文件路径可以是相对路径（相对于配置文件）或绝对路径（以 / 或 ~ 开头）。
这个功能特别适合：
- 将敏感信息（如 API Key）保存在单独文件中
- 在多个配置文件间共享配置片段
- 引入大型指令文件而不让配置文件变得臃肿
目录结构说明
.opencode 和 ~/.config/opencode 目录使用复数名称作为子目录：
agents/- Agent 定义commands/- 命令定义modes/- 模式定义plugins/- 插件skills/- 技能tools/- 工具themes/- 主题
为了向后兼容，单数名称（如 agent/）也是支持的。
小结
OpenCode 的配置系统设计得相当灵活，通过合理配置，你可以打造出完全符合个人或团队需求的 AI 编程助手。建议从简单配置开始，随着使用深入逐步添加更多定制项。
配置文件的 Schema 定义在 opencode.ai/config.json，支持自动补全的编辑器会大大提升配置效率。如果你在配置过程中遇到问题，可以访问 OpenCode 官方文档或加入 Discord 社区获取帮助。