跳至内容
OpenCode
app.header.homeapp.header.docs

配置

使用 OpenCode JSON 配置文件。

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

格式

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

opencode.jsonc
{
  "$schema": "https://opencode.ac.cn/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 目录 - 代理、命令、插件
  6. 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）- 运行时覆盖
  7. 托管配置文件（macOS 上的 /Library/Application Support/opencode/）- 管理员控制
  8. macOS 托管偏好设置（通过 MDM 的 .mobileconfig）- 最高优先级，用户不可覆盖

这意味着项目配置可以覆盖全局默认设置，全局配置可以覆盖远程组织默认设置。托管设置覆盖所有其他设置。

远程

组织可以通过 .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 中。全局配置用于用户范围的服务器/运行时偏好设置，例如提供程序、模型和权限。

对于 TUI 特定设置，请使用 ~/.config/opencode/tui.json。

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

按项目

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

对于项目特定的 TUI 设置，请在其旁边添加 tui.json。

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

这也适合提交到 Git，并使用与全局配置相同的架构。

自定义路径

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

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

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

自定义目录

使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。此目录将像标准 .opencode 目录一样被搜索代理、命令、模式和插件，并且应遵循相同的结构。

终端窗口
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

这些目录需要管理员/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 字典中

<?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: 电脑 > 配置描述文件 > 上传 > 作用范围到目标设备或智能组
  • FleetDM: 将 .mobileconfig 添加到您的 gitops 仓库中 mdm.macos_settings.custom_settings 下，并运行 fleetctl apply

在设备上验证

双击 .mobileconfig 以在本地安装进行测试（显示在“系统设置”>“隐私与安全性”>“描述文件”中），然后运行

终端窗口
opencode debug config

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

架构

服务器/运行时配置架构在 opencode.ai/config.json 中定义。

TUI 配置使用 opencode.ai/tui.json。

您的编辑器应该能够根据架构进行验证和自动完成。

TUI

使用专用的 tui.json（或 tui.jsonc）文件进行 TUI 特定设置。

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

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

opencode.json 中的旧版 theme、keybinds 和 tui 键已弃用，并会在可能的情况下自动迁移。

服务器

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

opencode.json
{
  "$schema": "https://opencode.ac.cn/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["https://: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.ac.cn/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

在此处了解有关工具的更多信息.

模型

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

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

small_model 选项为标题生成等轻量级任务配置了一个单独的模型。默认情况下，OpenCode 会尝试使用您的提供程序中可用的更便宜的模型，否则会回退到您的主模型。

提供程序选项可以包括 timeout、chunkTimeout 和 setCacheKey

opencode.json
{
  "$schema": "https://opencode.ac.cn/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}
  • timeout - 请求超时时间（毫秒）（默认：300000）。设置为 false 禁用。
  • chunkTimeout - 流式响应块之间的超时时间（毫秒）。如果未能及时收到数据块，请求将被中止。
  • setCacheKey - 确保为指定提供程序始终设置缓存键。

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

提供程序特定选项

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

Amazon Bedrock

Amazon Bedrock 支持 AWS 特定配置

opencode.json
{
  "$schema": "https://opencode.ac.cn/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 优先。

了解更多关于 Amazon Bedrock 配置.

主题

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

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

在此处了解更多信息.

代理

您可以通过 agent 选项为特定任务配置专用代理。

opencode.jsonc
{
  "$schema": "https://opencode.ac.cn/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 文件定义代理。在此处了解更多信息。

默认代理

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

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

默认代理必须是主代理（而不是子代理）。这可以是内置代理，如 "build" 或 "plan"，或您定义的自定义代理。如果指定的代理不存在或是一个子代理，OpenCode 将回退到 "build" 并发出警告。

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

共享

您可以通过 share 选项配置共享功能。

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

它接受

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

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

命令

您可以通过 command 选项配置用于重复任务的自定义命令。

opencode.jsonc
{
  "$schema": "https://opencode.ac.cn/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 文件定义命令。在此处了解更多信息。

快捷键

在 tui.json 中自定义按键绑定。

tui.json
{
  "$schema": "https://opencode.ac.cn/tui.json",
  "keybinds": {}
}

在此处了解更多信息.

快照

OpenCode 使用快照来跟踪代理操作期间的文件更改，使您能够在会话中撤消和恢复更改。快照默认启用。

对于大型仓库或拥有许多子模块的项目，快照系统可能会导致索引缓慢和大量磁盘使用，因为它使用内部 git 仓库跟踪所有更改。您可以使用 snapshot 选项禁用快照。

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

请注意，禁用快照意味着代理所做的更改无法通过 UI 回滚。

自动更新

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

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

如果您不想要更新，但希望在新版本可用时收到通知，请将 autoupdate 设置为 "notify"。请注意，这仅适用于未使用 Homebrew 等包管理器安装的情况。

格式化程序

您可以通过 formatter 选项配置代码格式化程序。

opencode.json
{
  "$schema": "https://opencode.ac.cn/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.ac.cn/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

在此处了解有关权限的更多信息.

压缩

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

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

监视器

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

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

模式遵循 glob 语法。使用此功能可以从文件监视中排除嘈杂的目录。

MCP 服务器

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

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

在此处了解更多信息.

插件

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

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

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

在此处了解更多信息.

指令

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

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

它接受一个包含指令文件路径和 glob 模式的数组。在此处了解更多关于规则的信息。

禁用的提供程序

您可以通过 disabled_providers 选项禁用自动加载的提供程序。当您想阻止某些提供程序加载，即使它们的凭据可用时，此功能很有用。

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

disabled_providers 选项接受一个提供程序 ID 数组。当提供程序被禁用时

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

启用的提供程序

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

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

当您想限制 OpenCode 仅使用特定提供程序，而不是逐个禁用它们时，此功能很有用。

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

实验性功能

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

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

变量

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

环境变量

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

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

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

文件

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

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

文件路径可以是

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

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

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