跳转到内容
OpenCode
HomeDocs

配置

使用 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"

最终生效的配置会同时包含这三个字段。

优先级顺序

配置来源的加载顺序如下（后面加载的会覆盖前面的冲突值）：

  1. 远程配置（.well-known/opencode）—— 组织级默认配置
  2. 全局配置（~/.config/opencode/opencode.json）—— 用户个人偏好
  3. 自定义配置路径（OPENCODE_CONFIG 环境变量）—— 自定义覆盖
  4. 项目配置（项目根目录中的 opencode.json）—— 项目级设置
  5. .opencode 目录 —— Agents、命令、插件等
  6. 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）—— 运行时覆盖

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

远程配置

组织可以通过 .well-known/opencode 端点提供默认配置。当你在支持该能力的提供商上完成认证时，会自动拉取该配置。

远程配置最先加载，作为基础层，其它配置（全局、项目等）可以在此基础上进行覆盖。

例如，组织可能通过远程配置提供一组默认关闭的 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
    }
  }
}

全局配置

全局配置路径为 ~/.config/opencode/opencode.json。适合存放用户级的偏好设置，如主题、提供商或快捷键等。

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

项目级配置

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

OpenCode 启动时，会在当前目录查找配置文件，若没找到则一路向上查找到最近的 Git 根目录。

项目配置文件适合提交到 Git，使用的 schema 与全局配置相同。

自定义路径

通过 OPENCODE_CONFIG 环境变量指定自定义配置文件路径：

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

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

自定义目录

通过 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。

该目录会像标准 .opencode 目录一样被用来搜索 agents、commands、modes 和 plugins，目录结构也应保持一致。

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

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

Schema

配置文件的 schema 定义在 opencode.ai/config.json。

大多数编辑器可以基于该 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 —— 自定义滚动速度倍率（默认：1，最小：1）。当 scroll_acceleration.enabled 为 true 时会被忽略。
  • diff_style —— 控制 diff 显示方式："auto" 会根据终端宽度自适应布局，"stacked" 则始终使用单列视图。

在此了解更多 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,
    "cors": ["http://localhost:5173"]
  }
}

可用选项：

  • port —— 监听端口
  • hostname —— 监听主机名。当启用 mdns 且未设置主机名时，默认 0.0.0.0
  • mdns —— 启用 mDNS 服务发现，使局域网中的其他设备可以发现你的 OpenCode 服务器
  • cors —— 当通过浏览器客户端访问 HTTP 服务器时，允许的额外 Origin（需要完整 Origin，如 https://app.example.com）

了解更多服务器相关内容。

Tools

可以通过 tools 选项控制 LLM 可用的工具：

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

在此了解更多工具配置。

Models

可以通过 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 —— 确保为该提供商始终设置缓存 Key。

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

提供商特定选项

有些提供商在通用选项（如 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 中的命名 profile（默认从 AWS_PROFILE 环境变量获取）
  • endpoint —— 自定义 VPC Endpoint 的 URL。它是通用 baseURL 选项的 AWS 语义别名；若两者都设置，则 endpoint 优先。

查看更多 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/agent/ 或 .opencode/agent/ 中通过 Markdown 文件定义 Agents。了解更多。

默认 Agent

通过 default_agent 选项可以设置默认 Agent。当未显式指定 Agent 时，就会使用这个配置：

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

默认 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 命令来分享对话。

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/command/ 或 .opencode/command/ 下通过 Markdown 文件定义命令。了解更多。

Keybinds

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

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

了解更多快捷键配置。

Autoupdate

OpenCode 启动时会自动检查并下载新版本。你可以通过 autoupdate 选项禁用这一行为：

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

如果你不想自动更新，但希望在有新版本时收到通知，可以将 autoupdate 设置为 "notify"。

Formatters

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

了解更多格式化器配置。

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
  }
}
  • auto —— 当上下文接近上限时自动进行压缩（默认：true）
  • prune —— 为节省 Token，移除旧的工具输出（默认：true）

Watcher

可以通过 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": {}
}

了解更多 MCP 服务器配置。

Plugins

插件可以为 OpenCode 扩展自定义工具、Hook 和集成能力。

你可以将插件文件放在 .opencode/plugin/ 或 ~/.config/opencode/plugin/ 目录中，也可以通过 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 选项禁用某些自动加载的提供商。这在你即便配置了凭证，也不希望使用某些提供商时非常有用：

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

disabled_providers 接受提供商 ID 的数组。当某个提供商被禁用后：

  • 即便设置了环境变量也不会被加载
  • 即便通过 /connect 配置了 API Key 也不会被启用
  • 对应提供商的模型不会出现在模型列表中

Enabled providers

可以通过 enabled_providers 配置一个“允许列表”，当该选项被设置时，只有出现在其中的提供商会被启用，其它都会被忽略：

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

这在你想只允许使用少数几个提供商，而不是逐个禁用其它提供商时非常有用。

如果某个提供商同时出现在 enabled_providers 和 disabled_providers 中，则出于向后兼容的考虑，disabled_providers 会优先生效。

Experimental

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 Key）保存在单独的文件中
  • 引入较大的说明文档而不污染配置文件
  • 在多个配置文件之间共享公共配置片段