进阶 opencode.ai 2026-11-11 16:13:22 · 13 阅读

第4章 OpenCode 配置指南

在你的项目中创建 opencode.jsonc 文件来配置 OpenCode。添加 $schema$ 字段以启用编辑器校验,然后仅设置你需要的选项。

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

你也可以让 OpenCode 帮你更新此文件。

OpenCode 支持 JSON 和 JSONC。如果你需要注释或尾随逗号,请使用 JSONC。

opencode.jsonc{
  "$schema": "https://opencode.ai/config.json",
  // 默认使用此模型。
  "model": "anthropic/claude-sonnet-5-5",
}

将受管理的机器级设置放在系统配置目录中:

平台 目录
macOS /Library/Application Support/opencode
Linux /etc/opencode
Windows %ProgramData%\opencode

系统目录的作用与全局目录类似。除了 opencode.json(c),它为机器上的每个用户加载 agents/、commands/、skills/ 和 plugins/:

Files
/etc/opencode/
├── opencode.json
├── agents/review.md
├── commands/release.md
└── skills/deploy/SKILL.md

在 macOS 上,OpenCode 还会读取 MDM 工具部署到 ai.opencode.managed 域中的受管理偏好设置。用户特定的配置文件会替换机器级的配置:

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

受管理设置的优先级最高,因此用户和项目无法覆盖其设置的值,且受管理偏好设置优先于系统目录中的设置。仅靠设置无法阻止用户添加提供商、MCP 服务器、代理或插件;请在受管理的配置中使用策略(policies)来强制执行限制。

将所有项目的用户设置放在全局配置中:

~/.config/opencode/opencode.json(c)

将项目设置放在以下任一文件中:

/home/user/projects/my-app/opencode.json(c)
/home/user/projects/my-app/.opencode/opencode.json(c)

OpenCode 从当前目录搜索到文件系统根目录。它首先从最远目录到最近目录合并直接的 opencode.json(c) 文件,然后按相同顺序合并 .opencode 目录内的文件。这意味着发现的每个 .opencode 配置都会覆盖每个直接配置。除非需要这种行为,否则在目录树中请始终使用其中一种形式。

例如,从 /home/user/projects/acme/packages/web 启动 OpenCode:

Files
/etc/opencode/opencode.json
~/.config/opencode/opencode.json

/home/user/projects/acme/
├── opencode.json
└── packages/
    └── web/
        ├── opencode.json
        └── src/

OpenCode 按以下从低到高的优先级应用这些文件:

~/.config/opencode/opencode.json
/home/user/projects/acme/opencode.json
/home/user/projects/acme/packages/web/opencode.json
/etc/opencode/opencode.json

包配置覆盖仓库配置中冲突的设置,而仓库配置覆盖全局配置。系统配置覆盖所有这些。不冲突的设置会被保留。来自全局和项目文件的策略按相反顺序评估,且系统策略优先于所有其他策略。

完整的 OpenCode 配置架构(schema)可在 opencode.ai/config.json 获取。在你的配置文件中添加 $schema 字段,以启用支持 JSON Schema 的编辑器中的校验和自动补全:

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

使用该架构作为可用字段、允许值和嵌套配置结构的唯一事实来源。

shell

设置终端和 shell 工具使用的 shell。

JSONC{
  "shell": "/bin/zsh",
}

model

以 provider/model 格式设置默认模型。根级别的默认值目前不会保留 #variant;代理和命令的模型引用可以选择一个。

JSONC{
  "model": "anthropic/claude-sonnet-5-5",
}

有关模型选择和本地模型,请参阅模型指南。

default_agent

选择会话未显式指定时使用的默认代理。

JSONC{
  "default_agent": "build",
}

有关内置和自定义代理,请参阅代理指南。

update

从全局配置控制更新检查。将 update 设为 "disable" 可跳过检查,"notify" 会在安装前显示可用更新,"auto" 会自动安装更新。省略时,update 默认为 "notify"。自动安装不会重启正在运行的服务器。需手动重启以激活已安装的更新。忽略项目级的值。

JSONC{
  "update": "notify",
}

username

设置用户名。OpenCode 接受此字段,但在对话中不显示。

JSONC{
  "username": "alice",
}

permissions

定义有序规则,允许、禁止或在代理对匹配资源使用工具前询问。

JSONC{
  "permissions": [
    {
      "action": "shell",
      "resource": "git push *",
      "effect": "ask",
    },
  ],
}

有关规则匹配和可用操作,请参阅权限指南。

policies

使用有序语句允许或禁止使用提供商、硬性拒绝权限检查、或阻止 MCP 服务器、技能或插件,且更广泛的配置可以覆盖这些语句。

JSONC{
  "policies": [
    { "action": "provider.use", "resource": "*", "effect": "deny" },
    { "action": "provider.use", "resource": "anthropic", "effect": "allow" },
    { "action": "tool.use", "resource": "shell:git push *", "effect": "deny" },
  ],
}

有关匹配、跨配置文件的优先级以及控制台管理的策略,请参阅策略指南。

agents

覆盖内置代理或定义具有自己的模型、指令、模式和权限的专用代理。

JSONC{
  "agents": {
    "reviewer": {
      "description": "审查变更而不编辑文件",
      "mode": "subagent",
      "system": "关注正确性、安全性和缺失的测试。",
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }],
    },
  },
}

有关所有代理选项和基于文件的代理,请参阅代理指南。

snapshots

启用或禁用文件系统快照,用于撤销和回退行为。

JSONC{
  "snapshots": false,
}

有关撤销和重做行为,请参阅快照指南。

watcher

忽略不应触发文件系统更新的文件和目录。

JSONC{
  "watcher": {
    "ignore": ["dist/**", "coverage/**"],
  },
}

formatter

在 write、edit 或 patch 工具更改文件后进行格式化。将 formatter 设为 true 以启用可用的内置格式化器。

JSONC{
  "formatter": true,
}

有关内置和自定义格式化器,请参阅格式化器指南。

media

控制 read 工具加载的过大图像在发送给模型前如何被缩放或拒绝。

JSONC{
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}

有关图像处理和限制,请参阅附件指南。

tool_output

设置从工具结果中保留的最大行数和字节数。

JSONC{
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200,
  },
}

websearch

选择 OpenCode 如何搜索网络。使用 "random" 自动选择可用提供商。

JSONC{
  "websearch": {
    "provider": "random",
  },
}

有关提供商、凭据、选择、速率限制和禁用搜索,请参阅网络搜索指南。

mcp

配置本地和远程 Model Context Protocol 服务器。全局 mcp.timeout 值适用于配置文件中定义的服务器;每个服务器的超时设置会覆盖它们。

JSONC{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["bunx", "@playwright/mcp"],
      },
    },
  },
}

有关远程服务器、OAuth、环境变量的超时的设置,请参阅 MCP 指南。

compaction

控制自动上下文压缩及其保留的近期上下文量。

JSONC{
  "compaction": {
    "auto": true,
    "keep": {
      "tokens": 15000,
    },
    "buffer": "15%",
  },
}

buffer 是在自动压缩开始之前保留的空闲模型上下文窗口比例。本地摘要仍是默认选项。通过提供商或模型策略为自动和手动请求启用原生提供商压缩:

JSONC{
  "providers": {
    "openai": {
      "settings": { "compaction": { "type": "native" } },
      "models": {
        "gpt-6.1-sol": { "settings": { "compaction": { "type": "summary" } } },
      },
    },
  },
}

模型设置覆盖提供商设置。自动压缩使用所选模型可用的输入预算。提供商检查点会在与本地摘要用于保留尾部的相同 compaction.keep.tokens 预算内保留最近的 user 消息。顶层 compaction.auto: false 会禁用新的自动压缩,而不会丢弃已安装的检查点。有关预算和溢出恢复,请参阅压缩指南。

warming

通过周期性瞬态请求保持最近活跃的模型会话处于热状态。预热默认禁用;设为 true 可在每个模型缓存过期前进行预热,最长 30 分钟。

JSONC{
  "warming": {
    "prompt": "Do not perform any work. Reply with exactly: OK",
    "interval": "auto",
    "duration": "30 minutes",
  },
}

提供商或模型的 settings.cache.warming 会覆盖此设置,settings.cache.ttl 设置提供商保留缓存的时长。有关请求行为、自定义和成本考虑,请参阅预热指南;有关 cache.ttl,请参阅缓存生命周期。

skills

添加 OpenCode 应搜索代理技能的目录或 URL。

JSONC{
  "skills": ["./team-skills", "https://example.com/.well-known/skills/"],
}

有关技能结构和 .opencode/skills/ 下的自动发现,请参阅技能指南。

commands

将可重用的斜杠命令定义为命名提示模板。

JSONC{
  "commands": {
    "review": {
      "description": "审查当前变更",
      "template": "审查当前 diff 的正确性和缺失的测试。",
    },
  },
}

有关参数、模型、代理和基于文件的命令,请参阅命令指南。

instructions

声明额外的指令文件、glob 模式或 HTTP(S) URL。OpenCode 会将其与发现的 AGENTS.md 文件一起加载。

JSONC{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"],
}

有关项目指令和 AGENTS.md,请参阅指令指南。

references

将本地目录或 Git 仓库作为命名的支持上下文提供。

JSONC{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "产品行为和术语",
    },
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

有关简写、可见性和路径解析,请参阅引用指南。

worktree

设置新本地工作树(worktree)的父目录。OpenCode 会附加请求或生成的工作树名称。

JSONC{
  "worktree": {
    "directory": "../worktrees",
  },
}

相对路径相对于项目保存的规范检出(canonical checkout)解析。这对全局和项目配置均适用;绝对路径按原样使用,~/ 相对于用户的家目录解析。例如,此全局配置将新工作树放在每个项目自己的 .lane/trees/ 目录下:

JSONC{
  "worktree": {
    "directory": ".lane/trees",
  },
}

若未设置此项,创建时将使用服务器数据目录下 worktree/<项目ID前六个字符>。工作树的创建和刷新会从项目的规范检出加载配置,包括其他克隆共享其项目 ID 的情况。更改此项不会移动现有的工作树。Git 是内置默认值。注册策略的插件会在该插件运行时自动成为默认值。项目操作使用规范检出的运行时。特定于策略的选项属于该插件,而非 worktree 配置对象。

plugins

从包或本地插件目录加载插件。当插件接受选项时,使用对象形式。

JSONC{
  "plugins": [
    "opencode-example-plugin",
    {
      "package": "./plugins/local",
      "options": {
        "enabled": true,
      },
    },
  ],
}

有关插件加载和配置,请参阅插件指南。

providers

配置提供商,添加或覆盖其模型、请求设置、请求头和模型变体。

JSONC{
  "providers": {
    "openai": {
      "models": {
        "gpt-6.1-sol-custom": {
          "modelID": "gpt-6.1-sol",
          "name": "GPT-6.1 Sol Custom",
          "limit": {
            "context": 200000,
            "output": 32000,
          },
        },
      },
    },
  },
}

Provider settings.transport: "websocket" 选择其会话 WebSocket。有关凭据、自定义端点、提供商包、WebSocket 传输和模型配置,请参阅提供商指南。

你可以在配置文件中使用时,使用变量替换来引用环境变量和文件内容。将引用放在 JSON 字符串内部。

环境变量

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

opencode.jsonc{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "providers": {
    "anthropic": {
      "settings": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
      },
    },
  },
}

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

文件内容

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

opencode.jsonc{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "settings": {
        "apiKey": "{file:~/.secrets/openai-key}",
      },
    },
  },
}

文件路径可以是:

  • 相对于配置文件目录
  • 绝对路径,或以 ~/ 开头指向家目录

如果文件不存在,它将被替换为空字符串。这些功能适用于:

  • 将 API 密钥等敏感数据保存在单独的文件中。
  • 在多个配置文件之间共享通用配置片段。

所有实验性设置都位于 experimental 键下:

opencode.jsonc{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "todo": true,
    "subagent_depth": 2,
    "background_compaction": true,
    "image_generate": { "model": "openai/gpt-image-2" },
    "location_idle_timeout": "4 hours",
  },
}

experimental.todo

将 todo 设为 true 可为代理提供 todowrite 工具以跟踪多步工作。默认为 false。

experimental.subagent_depth

subagent_depth 设置子代理可以启动自身子代理的深度。默认为 1,即子代理不能启动另一个子代理。

experimental.background_compaction

将 background_compaction 设为 true 可在需要之前后台写入压缩摘要,以便自动压缩不会暂停会话。默认为 false。有关其工作原理,请参阅压缩。

JSONC{
  "experimental": {
    "background_compaction": true,
  },
}

experimental.image_generate

image_generate 设置 experimental_image_generate 工具的默认模型,格式为 providerID/modelID,可选附带 #variant。如果该模型不可用或无法处理请求,OpenCode 会自动选择另一个图像模型。

JSONC{
  "experimental": {
    "image_generate": {
      "model": "openai/gpt-image-2",
    },
  },
}

experimental.location_idle_timeout

location_idle_timeout 控制项目位置在没有会话活动的情况下可以保持多久,之后 OpenCode 会卸载其服务。它接受持续时间(如 "2 hours"),默认为 "60 minutes"。正在运行的会话和后台任务会使位置保持加载。设为 false 以永不卸载空闲位置。项目配置可以覆盖全局值。

JSONC{
  "experimental": {
    "location_idle_timeout": false,
  },
}

experimental.policies 已弃用。请使用顶层 policies 代替。旧键仍然有效并会合并到 policies 中。

评论 (0)