跳转到内容
OpenCode
app.header.homeapp.header.docs

配置

使用 opencode JSON 配置。

您可以使用 JSON 配置文件配置 opencode。

格式

opencode 支持 JSON 和 JSONC（带注释的 JSON）格式。

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

位置

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

配置文件被合并在一起，而不是被替换。以下配置位置的设置被合并。仅当密钥冲突时，后面的配置才会覆盖前面的配置。保留所有配置中的非冲突设置。

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

优先级

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

  1. Remote config (来自 .well-known/opencode) - 组织默认值
  2. Global config (~/.config/opencode/opencode.json) - 用户首选项
  3. Custom config (OPENCODE_CONFIG env var) - 自定义覆盖
  4. Project config (项目中的 opencode.json) - 项目特定的设置
  5. .opencode 目录 - 代理、命令、插件
  6. Inline config (OPENCODE_CONFIG_CONTENT env var) - 运行时覆盖

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

Remote

组织可以通过 .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
    }
  }
}

Global

将全局 opencode 配置放在 ~/.config/opencode/opencode.json 中。使用全局配置来实现用户范围的首选项，例如主题、提供商或按键绑定。

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

Per Project

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

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

这也可以安全地签入 Git 并使用与全局模式相同的架构。

Custom Path

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

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

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

Custom Directory

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

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

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

模式

配置文件具有在 opencode.ai/config.json 中定义的架构。

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

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 - 控制差异渲染。 "auto" 适应终端宽度，"stacked" 始终显示单列。

在此处了解有关使用 TUI 的更多信息。

Server

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

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

您可以通过 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 - 确保始终为指定的提供商设置缓存键。

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

特定于提供商的选项

有些提供商支持除通用 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 env var 或 us-east-1）
  • profile - 来自 ~/.aws/credentials 的 AWS 命名配置文件（默认为 AWS_PROFILE env var）
  • endpoint - VPC 终端节点的自定义节点 URL。这是使用 AWS 特定术语的通用 baseURL 选项的别名。如果两者都指定，endpoint 优先。

了解有关 Amazon Bedrock 配置的更多信息。

Theme

您可以通过 opencode 配置中的 theme 选项配置要使用的主题。

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

在这里了解更多。

Agents

您可以通过 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 文件定义代理。 在这里了解更多。

Default Agent

您可以使用 default_agent 选项设置默认代理。当没有明确指定时，这将确定使用哪个代理。

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

默认代理必须是 Primary 代理（不是 Subagent）。这可以是内置代理（如 "build" 或 "plan"），也可以是您定义的 Custom Agent。如果指定的代理不存在或者是子代理，opencode 将回退到 "build" 并发出警告。

此设置适用于所有界面：TUI、CLI (opencode run)、桌面应用程序和 GitHub Action。

Share

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

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

这需要：

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

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

Command

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

您可以通过 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"。 请注意，这仅在未使用 Homebrew 等包管理器安装时才有效。

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 - 删除旧工具输出以保存 Tokens（默认值：true）。

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

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 选项禁用自动加载的提供商。当您想要阻止加载某些提供商（即使其凭据可用）时，这非常有用。

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

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

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

Enabled Providers

您可以通过 enabled_providers 选项指定允许的提供商列表。设置后，仅启用指定的提供商，所有其他提供商将被忽略。

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

当您想要限制 opencode 仅使用特定的提供商而不是逐一禁用它们时，这非常有用。

如果提供商同时出现在 enabled_providers 和 disabled_providers 中，则 disabled_providers 优先以保持一致性。

Experimental

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

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

Variables

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

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 密钥等敏感数据保存在单独的文件中。
  • 包含大型指令文件，而不会弄乱您的配置。
  • 跨多个配置文件共享通用配置片段。