配置

使用 OpenCode JSON 配置。

你可以使用 JSON 配置文件来配置 OpenCode。

格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）两种格式。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  // 主题配置
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

位置

你可以将配置文件放在几个不同的位置，它们有不同的优先级顺序。

注意： 配置文件是合并的，而不是替换。

配置文件是合并在一起的，而不是替换。以下配置位置的设置会被组合。后面的配置只会覆盖冲突的键。所有配置中不冲突的设置都会被保留。

例如，如果你的全局配置设置了 theme: "opencode" 和 autoupdate: true，而项目配置设置了 model: "anthropic/claude-sonnet-4-5"，最终配置将包含所有三个设置。

优先级顺序

配置源按以下顺序加载（后面的源会覆盖前面的）：

远程配置（来自 .well-known/opencode）- 组织默认值
全局配置（~/.config/opencode/opencode.json）- 用户偏好
自定义配置（OPENCODE_CONFIG 环境变量）- 自定义覆盖
项目配置（项目中的 opencode.json）- 项目特定设置
.opencode 目录 - agents、commands、plugins
内联配置（OPENCODE_CONFIG_CONTENT 环境变量）- 运行时覆盖

这意味着项目配置可以覆盖全局默认值，全局配置可以覆盖远程组织默认值。

注意： .opencode 和 ~/.config/opencode 目录的子目录使用复数名称：agents/、commands/、modes/、plugins/、skills/、tools/ 和 themes/。为了向后兼容，也支持单数名称（如 agent/）。

远程

组织可以通过 .well-known/opencode 端点提供默认配置。当你使用支持此功能的提供商进行身份验证时，会自动获取此配置。

远程配置首先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。

例如，如果你的组织提供了默认禁用的 MCP 服务器：

来自 .well-known/opencode 的远程配置

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

你可以在本地配置中启用特定的服务器：

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

全局

将全局 OpenCode 配置放在 ~/.config/opencode/opencode.json。使用全局配置来设置用户范围的偏好，如主题、提供商或快捷键。

全局配置会覆盖远程组织默认值。

项目级

在项目根目录添加 opencode.json。项目配置在标准配置文件中具有最高优先级 - 它会覆盖全局和远程配置。

提示： 将项目特定配置放在项目根目录。

当 OpenCode 启动时，它会在当前目录查找配置文件，或向上遍历到最近的 Git 目录。

这也可以安全地提交到 Git，并使用与全局配置相同的 schema。

自定义路径

使用 OPENCODE_CONFIG 环境变量指定自定义配置文件路径。

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

自定义配置在优先级顺序中位于全局配置和项目配置之间。

自定义目录

使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。此目录将像标准 .opencode 目录一样搜索 agents、commands、modes 和 plugins，并应遵循相同的结构。

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

自定义目录在全局配置和 .opencode 目录之后加载，因此它可以覆盖它们的设置。

Schema

配置文件有一个 schema，定义在 opencode.ai/config.json (opens in a new tab)。

你的编辑器应该能够基于 schema 进行验证和自动补全。

TUI

你可以通过 tui 选项配置 TUI 特定的设置。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

可用选项：

scroll_acceleration.enabled - 启用 macOS 风格的滚动加速。优先于 scroll_speed。
scroll_speed - 自定义滚动速度倍数（默认：3，最小：1）。如果 scroll_acceleration.enabled 为 true 则忽略。
diff_style - 控制 diff 渲染。"auto" 根据终端宽度自适应，"stacked" 始终显示单列。

在这里了解更多关于使用 TUI 的信息。

服务器

你可以通过 server 选项为 opencode serve 和 opencode web 命令配置服务器设置。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

可用选项：

port - 监听端口。
hostname - 监听主机名。当启用 mdns 且未设置主机名时，默认为 0.0.0.0。
mdns - 启用 mDNS 服务发现。这允许网络上的其他设备发现你的 OpenCode 服务器。
mdnsDomain - mDNS 服务的自定义域名。默认为 opencode.local。适用于在同一网络上运行多个实例。
cors - 从基于浏览器的客户端使用 HTTP 服务器时允许的额外 CORS 来源。值必须是完整的来源（协议 + 主机 + 可选端口），例如 https://app.example.com。

在这里了解更多关于服务器的信息。

工具

你可以通过 tools 选项管理 LLM 可以使用的工具。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

在这里了解更多关于工具的信息。

模型

你可以通过 provider、model 和 small_model 选项在 OpenCode 配置中配置要使用的提供商和模型。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model 选项为标题生成等轻量级任务配置单独的模型。默认情况下，如果你的提供商有更便宜的模型，OpenCode 会尝试使用它，否则会回退到你的主模型。

提供商选项可以包括 timeout 和 setCacheKey：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout - 请求超时时间（毫秒）（默认：300000）。设置为 false 可禁用。
setCacheKey - 确保为指定提供商始终设置缓存键。

你还可以配置本地模型。了解更多。

提供商特定选项

某些提供商支持除通用 timeout 和 apiKey 设置之外的额外配置选项。

Amazon Bedrock

Amazon Bedrock 支持 AWS 特定配置：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

region - Bedrock 的 AWS 区域（默认为 AWS_REGION 环境变量或 us-east-1）
profile - 来自 ~/.aws/credentials 的 AWS 命名配置文件（默认为 AWS_PROFILE 环境变量）
endpoint - VPC 端点的自定义端点 URL。这是使用 AWS 特定术语的通用 baseURL 选项的别名。如果两者都指定，endpoint 优先。

注意： Bearer 令牌（AWS_BEARER_TOKEN_BEDROCK 或 /connect）优先于基于配置文件的身份验证。详见身份验证优先级。

了解更多关于 Amazon Bedrock 配置。

主题

你可以通过 theme 选项在 OpenCode 配置中配置要使用的主题。

opencode.json

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

在这里了解更多。

Agents

你可以通过 agent 选项为特定任务配置专门的 agents。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "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": {
        // 为仅审查的 agent 禁用文件修改工具
        "write": false,
        "edit": false
      }
    }
  }
}

你也可以在 ~/.config/opencode/agents/ 或 .opencode/agents/ 中使用 markdown 文件定义 agents。在这里了解更多。

默认 Agent

你可以使用 default_agent 选项设置默认 agent。这决定了在未明确指定时使用哪个 agent。

opencode.json

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

默认 agent 必须是主 agent（不是子 agent）。这可以是内置 agent 如 "build" 或 "plan"，或者你定义的自定义 agent。如果指定的 agent 不存在或是子 agent，OpenCode 将回退到 "build" 并显示警告。

此设置适用于所有界面：TUI、CLI（opencode run）、桌面应用和 GitHub Action。

你可以通过 share 选项配置分享功能。

opencode.json

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

可选值：

"manual" - 允许通过命令手动分享（默认）
"auto" - 自动分享新对话
"disabled" - 完全禁用分享

默认情况下，分享设置为手动模式，你需要使用 /share 命令显式分享对话。

命令

你可以通过 command 选项为重复性任务配置自定义命令。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "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"
    }
  }
}

你也可以在 ~/.config/opencode/commands/ 或 .opencode/commands/ 中使用 markdown 文件定义命令。在这里了解更多。

快捷键

你可以通过 keybinds 选项自定义快捷键。

opencode.json

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

在这里了解更多。

自动更新

OpenCode 启动时会自动下载任何新更新。你可以使用 autoupdate 选项禁用此功能。

opencode.json

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

如果你不想更新但想在有新版本时收到通知，请将 autoupdate 设置为 "notify"。请注意，这仅在未使用 Homebrew 等包管理器安装时有效。

格式化器

你可以通过 formatter 选项配置代码格式化器。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

在这里了解更多关于格式化器的信息。

权限

默认情况下，opencode 允许所有操作而无需明确批准。你可以使用 permission 选项更改此设置。

例如，要确保 edit 和 bash 工具需要用户批准：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

在这里了解更多关于权限的信息。

压缩

你可以通过 compaction 选项控制上下文压缩行为。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto - 当上下文满时自动压缩会话（默认：true）。
prune - 删除旧的工具输出以节省 token（默认：true）。

监视器

你可以通过 watcher 选项配置文件监视器忽略模式。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

模式遵循 glob 语法。使用此选项排除文件监视中的嘈杂目录。

MCP 服务器

你可以通过 mcp 选项配置要使用的 MCP 服务器。

opencode.json

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

在这里了解更多。

插件

插件通过自定义工具、钩子和集成扩展 OpenCode。

将插件文件放在 .opencode/plugins/ 或 ~/.config/opencode/plugins/。你也可以通过 plugin 选项从 npm 加载插件。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

在这里了解更多。

指令

你可以通过 instructions 选项为你使用的模型配置指令。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

这接受一个路径和 glob 模式数组，指向指令文件。在这里了解更多关于规则的信息。

禁用的提供商

你可以通过 disabled_providers 选项禁用自动加载的提供商。当你想阻止某些提供商被加载时（即使它们的凭据可用），这很有用。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

注意： disabled_providers 优先于 enabled_providers。

disabled_providers 选项接受提供商 ID 数组。当提供商被禁用时：

即使设置了环境变量也不会加载。
即使通过 /connect 命令配置了 API 密钥也不会加载。
提供商的模型不会出现在模型选择列表中。

启用的提供商

你可以通过 enabled_providers 选项指定提供商白名单。设置后，只有指定的提供商会被启用，其他所有提供商都会被忽略。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

当你想限制 OpenCode 只使用特定提供商而不是逐个禁用它们时，这很有用。

注意： disabled_providers 优先于 enabled_providers。

如果一个提供商同时出现在 enabled_providers 和 disabled_providers 中，为了向后兼容，disabled_providers 优先。

实验性

experimental 键包含正在积极开发中的选项。

opencode.json

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

注意： 实验性选项不稳定。它们可能会在没有通知的情况下更改或删除。

变量

你可以在配置文件中使用变量替换来引用环境变量和文件内容。

环境变量

使用 {env:VARIABLE_NAME} 替换环境变量：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

如果环境变量未设置，它将被替换为空字符串。

文件

使用 {file:path/to/file} 替换文件内容：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是：

相对于配置文件目录
或以 / 或 ~ 开头的绝对路径

这些对于以下情况很有用：

将 API 密钥等敏感数据保存在单独的文件中。
包含大型指令文件而不使配置混乱。
在多个配置文件之间共享通用配置片段。

介绍提供商