Skip to content
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"，则最终配置将包含所有这三个设置。

全局

将全局 OpenCode 配置放在 ~/.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 目录一样被搜索智能体、命令、模式和插件，并且应遵循相同的结构。

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 的信息。

服务器

你可以配置 OpenCode 后端服务器。

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 服务器时，允许 CORS 的额外源。值必须是完整的源（协议 + 主机 + 可选端口），例如 https://app.example.com。

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

工具

你可以配置 OpenCode 智能体可用的工具。

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

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

模型

你可以配置默认模型和模型特定选项。

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

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

主题

你可以配置 TUI 的主题。

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

在此了解更多信息。

智能体

你可以定义具有特定指令和工具集的自定义智能体。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码的最佳实践和潜在问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名代码审查员。关注安全性、性能和可维护性。",
      "tools": {
        // 为仅限审查的智能体禁用文件修改工具
        "write": false,
        "edit": false,
      },
    },
  },
}

你也可以在 ~/.config/opencode/agent/ 或 .opencode/agent/ 中使用 markdown 文件定义智能体。在此了解更多信息。

默认智能体

你可以配置默认情况下使用的智能体。

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

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

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

分享

你可以配置会话的分享行为。

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

此选项接受：

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

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

命令

你可以通过将命令添加到配置中来自定义斜杠命令。

opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，显示任何失败项。\n专注于失败的测试并建议修复方案。",
      "description": "运行带有覆盖率的测试",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的支持 TypeScript 的新 React 组件。\n包含适当的类型和基本结构。",
      "description": "创建一个新组件",
    },
  },
}

你也可以在 ~/.config/opencode/command/ 或 .opencode/command/ 中使用 markdown 文件定义命令。在此了解更多信息。

按键绑定

你可以自定义 TUI 中的快捷键。

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

在此了解更多信息。

自动更新

你可以配置是否自动检查更新。

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

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

格式化程序

你可以配置用于格式化代码的工具。

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

在此了解更多关于格式化程序的信息。

权限

你可以配置智能体执行敏感操作（如运行 shell 命令）时的权限。

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

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

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

压缩

你可以配置会话历史记录的压缩行为。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}
  • auto - 当上下文已满时自动压缩会话（默认：true）。
  • prune - 删除旧的工具输出以节省令牌（默认：true）。

观察器

你可以配置工作目录中文件的观察行为。

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

模式遵循 glob 语法。使用此项从文件观察中排除干扰目录。

MCP 服务器

你可以配置要使用的 Model Context Protocol (MCP) 服务器。

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

在此了解更多信息。

插件

你可以配置要加载的插件。

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

在此了解更多信息。

指令

你可以指定额外的指令文件。

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

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

禁用的提供商

你可以禁用特定的模型提供商。

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

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

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

启用的提供商

你可以仅启用特定的模型提供商。

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

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

如果提供商同时出现在 enabled_providers 和 disabled_providers 中，为了向后兼容，disabled_providers 具有更高优先级。

实验性

你可以启用实验性功能。

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

变量

你可以在配置文件中使用变量。

环境变量

你可以引用环境变量。

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

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

文件

你可以引用文件内容。

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

文件路径可以是：

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

这些对于以下场景非常有用：

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