中文
文档
配置

配置

使用 OpenCode JSON 配置。

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

格式

OpenCode 同时支持 JSON 和 JSONC（带注释的 JSON）格式。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

位置

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

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

配置文件是被合并到一起的，而不是被替换。来自以下各配置位置的设置会被组合在一起。靠后的配置只会针对冲突的键覆盖靠前的配置。来自所有配置的非冲突设置都会被保留。

例如，如果你的全局配置设置了 autoupdate: true，而你的项目配置设置了 model: "anthropic/claude-sonnet-4-5"，最终的配置将同时包含这两项设置。

优先级顺序

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

  1. 远程配置（来自 .well-known/opencode）- 组织默认值
  2. 全局配置（~/.config/opencode/opencode.json）- 用户偏好
  3. 自定义配置（OPENCODE_CONFIG 环境变量）- 自定义覆盖
  4. 项目配置（项目中的 opencode.json）- 项目专属设置
  5. .opencode 目录 - agents、commands、plugins
  6. 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）- 运行时覆盖
  7. 托管配置文件（macOS 上的 /Library/Application Support/opencode/）- 由管理员控制
  8. macOS 托管偏好设置（通过 MDM 的 .mobileconfig）- 最高优先级，用户不可覆盖

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

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

远程

组织可以通过 .well-known/opencode 端点提供默认配置。当你向某个支持它的 provider 进行身份验证时，它会被自动抓取。

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

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

Remote config from .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。使用全局配置来设置面向整个用户的服务器/运行时偏好，例如 provider、模型和权限。

对于 TUI 专属设置，使用 ~/.config/opencode/tui.json。

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

按项目

在你的项目根目录中添加 opencode.json。在标准配置文件中，项目配置拥有最高的优先级 —— 它会同时覆盖全局配置和远程配置。

对于项目专属的 TUI 设置，在它旁边添加 tui.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 目录之后加载，因此它可以覆盖它们的设置。

托管设置

组织可以强制实施用户无法覆盖的配置。托管设置在最高优先级层级加载。

基于文件

在系统托管配置目录中放入一个 opencode.json 或 opencode.jsonc 文件：

平台路径
macOS/Library/Application Support/opencode/
Linux/etc/opencode/
Windows%ProgramData%\opencode

这些目录需要 admin/root 访问权限才能写入，所以用户无法修改它们。

macOS 托管偏好设置

在 macOS 上，OpenCode 从 ai.opencode.managed 偏好设置域读取托管偏好。通过 MDM（Jamf、Kandji、FleetDM）部署一个 .mobileconfig，这些设置就会被自动强制实施。

OpenCode 会检查这些路径：

  1. /Library/Managed Preferences/<user>/ai.opencode.managed.plist
  2. /Library/Managed Preferences/ai.opencode.managed.plist

plist 的键直接映射到 opencode.json 字段。MDM 元数据键（PayloadUUID、PayloadType 等）会被自动剥离。

创建 .mobileconfig

使用 ai.opencode.managed PayloadType。OpenCode 配置键直接放在 payload dict 中：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.opencode.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.opencode.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.opencode</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

用 uuidgen 生成唯一的 UUID。自定义这些设置以符合你组织的要求。

通过 MDM 部署

  • Jamf Pro： Computers > Configuration Profiles > Upload > 将作用范围限定到目标设备或智能组
  • FleetDM： 将该 .mobileconfig 添加到你的 gitops 仓库中 mdm.macos_settings.custom_settings 下，并运行 fleetctl apply

在设备上验证

双击该 .mobileconfig 在本地安装以进行测试（会显示在 System Settings > Privacy & Security > Profiles 中），然后运行：

opencode debug config

所有托管偏好设置键都会出现在解析后的配置中，且无法被用户或项目配置覆盖。

Schema

服务器/运行时配置 schema 定义在 opencode.ai/config.json (opens in a new tab)。

TUI 配置使用 opencode.ai/tui.json (opens in a new tab)。

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

TUI

为 TUI 专属设置使用一个专用的 tui.json（或 tui.jsonc）文件。

tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

使用 OPENCODE_TUI_CONFIG 指向一个自定义的 TUI 配置文件。

设置 attention.enabled 以开启 TUI 桌面通知和声音。参见 TUI attention。

opencode.json 中旧的 theme、keybinds 和 tui 键已被弃用，并在可能时被自动迁移。

Server

你可以通过 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 额外允许的来源。值必须是完整的来源（scheme + host + 可选端口），例如 https://app.example.com。

在此了解更多关于服务器的内容。

Shell

你可以使用 shell 选项配置交互式终端所用的 shell。兼容的 shell 也会用于 agent 的工具调用。

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

如果未指定，OpenCode 会根据你的操作系统自动发现并使用一个合理的默认值（例如 Windows 上的 pwsh 或 cmd.exe，macOS/Linux 上的 /bin/zsh 或 /bin/bash）。你可以提供一个绝对路径或一个简短名称。

Tools

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

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

在此了解更多关于工具的内容。

Models

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

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

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

Provider 选项可以包含 timeout、chunkTimeout 和 setCacheKey：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - 请求超时时间（毫秒）（默认：300000）。设为 false 以禁用。
  • chunkTimeout - 流式响应分块之间的超时时间（毫秒）。如果没有分块及时到达，请求会被中止。
  • setCacheKey - 确保始终为指定的 provider 设置缓存键。

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

Image attachments

OpenCode 会在将图片附件发送给模型之前对其进行规范化处理。默认情况下，当图片超过 2000x2000 像素或 5242880 base64 字节时会被缩放。

使用 attachment.image 选项配置图片附件限制：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}
  • auto_resize - 在 provider 请求之前缩放超出所配置限制的图片。设为 false 则改为拒绝过大的图片。
  • max_width - 缩放或拒绝之前的最大图片宽度（像素）。
  • max_height - 缩放或拒绝之前的最大图片高度（像素）。
  • max_base64_bytes - 编码后图片负载的最大大小。这是 base64 负载的大小，而非原始文件大小。

如果缩放后图片仍然无法容纳，OpenCode 会省略过大的工具结果图片，或对用户提供的过大图片以图片尺寸错误失败。

Provider 特定选项

某些 provider 在通用的 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 命名 profile（默认为 AWS_PROFILE 环境变量）
  • endpoint - VPC 端点的自定义端点 URL。这是用 AWS 特定术语表示的通用 baseURL 选项的别名。如果两者都指定，endpoint 优先。

注意： Bearer token（AWS_BEARER_TOKEN_BEDROCK 或 /connect）的优先级高于基于 profile 的身份验证。详见 身份验证优先级。

了解更多关于 Amazon Bedrock 配置的内容。

Themes

在 tui.json 中设置你的 UI 主题。

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

在此了解更多。

Agents

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

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": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

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

Default agent

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

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

默认 agent 必须是一个主 agent（而非子 agent）。它可以是像 "build" 或 "plan" 这样的内置 agent，也可以是你定义的一个 自定义 agent。如果指定的 agent 不存在或是一个子 agent，OpenCode 会回退到 "build" 并给出警告。

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

Sharing

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

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

它可取：

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

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

Commands

你可以通过 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

在 tui.json 中用 keybinds 自定义 TUI 键盘快捷键。

tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

keybinds 会与内置默认值合并，所以你只需配置你想更改的那些快捷键。

在此了解更多。

Snapshot

OpenCode 使用快照在 agent 操作期间跟踪文件改动，使你能够在一个会话内撤销和还原改动。快照默认启用。

对于大型仓库或拥有许多子模块的项目，快照系统会使用一个内部 git 仓库跟踪所有改动，这可能导致索引缓慢和显著的磁盘占用。你可以使用 snapshot 选项禁用快照。

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

注意，禁用快照意味着 agent 所做的改动无法通过 UI 回滚。

Autoupdate

OpenCode 会在启动时自动下载任何新的更新。你可以用 autoupdate 选项禁用此行为。

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

如果你不想要更新，但希望在有新版本可用时收到通知，将 autoupdate 设置为 "notify"。 注意，这仅在它不是通过 Homebrew 之类的包管理器安装时才有效。

Formatters

你可以通过 formatter 选项启用和配置代码格式化工具。省略它则保持格式化工具禁用。

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

使用对象，可以在保持内置启用的同时，配置覆盖项或自定义格式化工具。

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"]
    }
  }
}

在此了解更多关于格式化工具的内容。

LSP Servers

你可以通过 lsp 选项启用和配置 LSP 服务器。省略它则保持 LSP 禁用。

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

使用对象，可以在保持内置启用的同时，配置覆盖项或自定义 LSP 服务器。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

在此了解更多关于 LSP 服务器的内容。

Permissions

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

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

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

在此了解更多关于权限的内容。

Compaction

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

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}
  • auto - 当上下文已满时自动压缩会话（默认：true）。
  • prune - 移除旧的工具输出以节省 token（默认：true）。
  • reserved - 用于压缩的 token 缓冲。留出足够的窗口以避免压缩期间溢出

Watcher

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

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

模式遵循 glob 语法。用它来将噪声较多的目录从文件监视中排除。

MCP servers

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

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

在此了解更多。

Plugins

插件 用自定义工具、钩子和集成扩展 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

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

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

它接受一个由指令文件路径和 glob 模式组成的数组。在此了解更多关于规则的内容。

Disabled providers

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

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

注意： disabled_providers 的优先级高于 enabled_providers。

disabled_providers 选项接受一个 provider ID 的数组。当一个 provider 被禁用时：

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

Enabled providers

你可以通过 enabled_providers 选项指定一个 provider 的允许列表。设置后，只有指定的 provider 会被启用，所有其他的都会被忽略。

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

当你想将 OpenCode 限制为只使用特定的 provider，而不是逐个禁用它们时，这很有用。

注意： disabled_providers 的优先级高于 enabled_providers。

如果某个 provider 同时出现在 enabled_providers 和 disabled_providers 中，为向后兼容，disabled_providers 优先。

Experimental

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

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

警告： 实验性选项并不稳定。它们可能会在没有通知的情况下更改或被移除。

变量

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

Env vars

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

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

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

Files

使用 {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 密钥等敏感数据保存在单独的文件中。
  • 包含大型指令文件而不让你的配置变得杂乱。
  • 在多个配置文件间共享通用的配置片段。
介绍提供商