OpenCode v2 配置工程实战：Config 优先级、JSONC、变量替换与多环境治理

长不大的杨瑞杰2026-11-04 16:32

OpenCode v2 配置工程实战：Config 优先级、JSONC、变量替换与多环境治理

这是《OpenCode v2 实战：从零搭建企业级 AI 编程助手》专题的第 21 篇。上一篇建立了 Snapshots、Compaction、Instructions 与 Formatters 的会话可靠性闭环；这一篇继续处理最容易被低估的基础设施问题：同一个 OpenCode 在不同目录、机器和账号下为什么表现不同，配置冲突怎样定位，密钥怎样与仓库分离，团队基线又怎样在允许项目自定义的同时保持可控。

OpenCode v2 的配置不是"读取一个 JSON 文件"这么简单。它会在系统、用户和项目目录中发现多个配置文档，按来源和距离合并；.opencode 目录中的配置与直接放在目录下的配置还有独立的覆盖顺序。再叠加系统托管设置、策略、环境变量、文件替换和实验项，靠直觉修改很容易得到"文件语法正确，但运行结果不对"的现场。

本文依据 2026 年 10 月 29 日可见的 OpenCode v2 官方 Config、CLI、Policies、Permissions、Providers、Instructions 与 Troubleshooting 文档整理。示例中的账号、域名、路径、模型和指标均为演示数据，不包含真实凭据。

一、先建立配置心智模型

1. 配置是多层合并，不是单文件覆盖

OpenCode 会保留不冲突的字段，只让更高优先级来源覆盖同名设置。假设全局配置定义默认模型和输出限制，项目配置只定义 Formatter，那么最终结果会同时拥有这三项，而不是只剩项目文件。

jsonc 复制代码 
// 全局配置：~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-6.1-sol",
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200,
  },
}
jsonc 复制代码 
// 项目配置：./opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true,
}

可以把最终配置理解为一个有来源标记的合并结果：

text 复制代码 
系统托管设置
  ↑ 最高优先级
系统配置目录
  ↑
更近的项目配置
  ↑
更远的项目配置
  ↑
用户全局配置

2. 配置、权限和策略不是同一层控制

普通设置决定默认模型、输出上限或是否启用 Formatter；Permissions 决定工具执行时允许、拒绝还是询问；Policies 则能在更高层阻止 Provider、MCP、Skill、Plugin 或某类工具资源。三者不要混成一个概念。

控制面 典型问题 适合放置的位置
Config 默认模型、Shell、输出上限是什么 全局或项目配置
Permissions git push 执行前是否询问 Agent 或项目权限规则
Policies 某 Provider 或 Plugin 是否可用 组织、系统或 Console 管理策略
jsonc 复制代码 
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ],
  "policies": [
    { "action": "tool.use", "resource": "shell:git push --force *", "effect": "deny" }
  ]
}

3. 先决定所有权，再决定文件位置

配置冲突往往不是技术问题，而是所有权问题。个人偏好放全局，仓库可复现规则放项目，机器强制边界放系统配置，企业不可绕过的限制放托管设置或管理策略。

yaml 复制代码 
ownership:
  personal: theme, preferred_model
  repository: formatter, watcher, instructions
  machine: approved_plugins, network_defaults
  organization: provider_allowlist, hard_denies

如果一个字段同时出现在四层，维护者就必须回答"谁有最终决定权"。回答不清楚时，配置漂移只是时间问题。

二、JSON 与 JSONC 怎样选

1. JSONC 更适合人工维护

OpenCode 同时支持 JSON 和 JSONC。JSONC 允许注释和尾随逗号，适合解释字段来源、变更原因和临时兼容逻辑。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  // 团队默认使用稳定模型；灰度模型由专用 Agent 指定。
  "model": "openai/gpt-6.1-sol",
  "formatter": true,
}

机器生成配置时仍可使用 JSON，但不要让生成器反复重写人工维护的 JSONC，否则注释、字段顺序和审计上下文会丢失。

2. $schema 是最低成本的防错层

在配置根节点加入官方 Schema，可以让支持 JSON Schema 的编辑器提供补全、类型检查和枚举提示。

json 复制代码 
{
  "$schema": "https://opencode.ai/config.json"
}

Schema 应当被视为当前版本字段和嵌套形状的权威来源。博客、旧示例和团队 Wiki 都可能落后；当文档与安装版本表现不一致时，还要固定版本并核对实际运行结果。

3. 语法有效不等于语义正确

下面的 JSONC 语法有效，但风险很大：项目配置试图控制自动更新，把实验项当稳定能力，并把密钥直接写进仓库。

jsonc 复制代码 
{
  "update": "auto",
  "experimental": {
    "background_compaction": true,
  },
  "providers": {
    "openai": {
      "settings": {
        "apiKey": "REPLACE_WITH_REAL_KEY"
      }
    }
  }
}

官方配置语义中，更新策略属于全局控制，项目级值会被忽略；实验项可能随版本变更；密钥则应使用变量或独立文件注入。

三、配置位置与发现规则

1. 系统配置用于机器级基线

OpenCode 的系统配置目录按平台区分：

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

系统目录不仅可以放 opencode.json(c)，还可以为所有用户提供 agents/、commands/、skills/ 和 plugins/。

text 复制代码 
/etc/opencode/
├── opencode.jsonc
├── agents/review.md
├── commands/release.md
└── skills/deploy/SKILL.md

系统配置适合机器级基线，但"能设置"不等于"能阻止用户扩展"。如果要强制限制 Provider、MCP、Agent、Skill 或 Plugin，应配合 Policies。

2. 全局配置用于个人跨项目默认值

用户全局配置位于：

text 复制代码 
~/.config/opencode/opencode.jsonc

适合放个人默认模型、常用输出限制、更新通知和跨项目通用 Agent。不要把只在某个仓库成立的构建命令或内部目录结构放入全局配置。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-6.1-sol",
  "update": "notify",
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200
  }
}

3. 项目配置会沿目录向上发现

项目配置可直接放在目录中，也可放在 .opencode 目录中：

text 复制代码 
/repo/opencode.jsonc
/repo/.opencode/opencode.jsonc

OpenCode 从当前目录向文件系统根部搜索。它先按"从远到近"合并直接配置，再按同样顺序合并所有 .opencode 配置。因此，每个被发现的 .opencode 配置都会覆盖所有直接配置中的冲突字段。

text 复制代码 
/repo/opencode.jsonc                     先合并
/repo/packages/web/opencode.jsonc        再覆盖
/repo/.opencode/opencode.jsonc           然后覆盖直接配置
/repo/packages/web/.opencode/opencode.jsonc  最后覆盖

除非团队明确需要这种两阶段覆盖，否则应在一棵目录树内统一选择直接文件或 .opencode 文件，降低认知成本。

四、完整优先级怎样计算

1. 普通设置从低到高合并

假设从 /home/dev/acme/packages/web 启动 OpenCode，存在全局、仓库和包级配置，普通设置的大致覆盖关系是：

text 复制代码 
用户全局配置
  < 仓库根配置
  < packages/web 配置
  < 系统配置
  < macOS 托管偏好（如适用）

更近的项目文件覆盖更远的项目文件；系统配置又覆盖用户和项目设置。macOS 的托管偏好优先级最高，其中用户专属托管配置高于机器级托管配置。

2. .opencode 是第二轮覆盖

最容易误判的是直接配置和 .opencode 配置的关系。它不是"同目录谁更近谁赢"，而是先合并全部直接配置，再合并全部 .opencode 配置。

jsonc 复制代码 
// /repo/packages/web/opencode.jsonc
{ "formatter": false }
jsonc 复制代码 
// /repo/.opencode/opencode.jsonc
{ "formatter": true }

即使 .opencode 文件离当前目录更远，它仍可能在第二轮合并中覆盖更近的直接文件。排障时必须把两类文件分开列出。

3. Policies 的评估方向不同

普通设置和 Policies 不应套用同一套"最近文件覆盖"直觉。官方说明中，全局与项目 Policies 以反向顺序评估，而系统 Policies 仍高于它们。组织安全规则要在变更评审中单独验证最终效果。

yaml 复制代码 
verification:
  config_value: inspect_effective_setting
  permission_rule: exercise_matching_resource
  policy_rule: test_allow_and_deny_cases

只看文件文本不能证明安全边界生效；至少要准备一个应允许案例和一个应拒绝案例。

五、搭建可维护的团队配置基线

1. 仓库根文件只放共同约束

仓库根配置应尽量稳定，让所有开发者和 CI 得到一致行为。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true,
  "watcher": {
    "ignore": ["dist/**", "coverage/**", ".cache/**"]
  },
  "instructions": [
    "CONTRIBUTING.md",
    "docs/engineering/*.md"
  ],
  "tool_output": {
    "max_lines": 2500,
    "max_bytes": 65536
  }
}

默认模型如果涉及成本、地区或账号授权差异，可以留在全局层；只有团队能够保证 Provider 可用性时，才把它固定到仓库。

2. 模块配置只覆盖真实差异

大型 Monorepo 可以在子目录配置不同的 Formatter、Instructions 或 Agent，但不要复制根配置的全部字段。

jsonc 复制代码 
// packages/mobile/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "../../docs/engineering/common.md",
    "./docs/mobile-guidelines.md"
  ],
  "watcher": {
    "ignore": ["build/**", ".gradle/**"]
  }
}

复制会让未来修改只能靠人工同步，最终形成看似相同、细节不同的配置岛。

3. 强制边界与项目偏好分离

机器级配置可以放允许的插件和稳定基线，组织级 Policy 阻止未批准能力，项目文件保留业务差异。

jsonc 复制代码 
{
  "policies": [
    { "action": "provider.use", "resource": "*", "effect": "deny" },
    { "action": "provider.use", "resource": "openai", "effect": "allow" },
    { "action": "plugin.use", "resource": "approved-*", "effect": "allow" }
  ]
}

规则命名、匹配方向和覆盖关系应以当前 Policies Schema 与实际测试为准，不能从伪代码直接复制到生产。

六、环境变量替换的正确用法

1. 使用 {env:NAME} 引用环境变量

OpenCode 可以在 JSON 字符串中展开环境变量：

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "providers": {
    "openai": {
      "settings": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

变量未设置时会被替换为空字符串，而不是自动报错。因此启动脚本必须在 OpenCode 之前验证必需变量。

powershell 复制代码 
$required = @('OPENCODE_MODEL', 'OPENAI_API_KEY')
$missing = $required | Where-Object { -not [Environment]::GetEnvironmentVariable($_) }
if ($missing.Count -gt 0) {
  throw "Missing required variables: $($missing -join ', ')"
}
opencode

2. 不要把环境变量当完整密钥治理

环境变量能避免把密钥写进 Git，但不能自动解决进程继承、日志打印、崩溃转储和终端历史泄露。

yaml 复制代码 
secret_controls:
  source: approved_secret_manager
  lifetime: process_scoped
  logging: redacted
  rotation: scheduled
  validation: fail_before_start

CI 中应使用平台的 Secret 注入能力，并限制变量只在需要的 Job 与 Step 可见。

3. 空字符串是必须监控的失败模式

如果 Provider 收到空 apiKey，错误可能表现为 401、匿名限流或落到另一条认证路径。排障时验证"变量存在且非空"，不要输出变量值。

bash 复制代码 
test -n "$OPENAI_API_KEY" || {
  echo "OPENAI_API_KEY is missing" >&2
  exit 1
}
exec opencode

审计日志只记录变量名、来源类别和是否存在，不记录长度、前缀或明文。

七、文件替换与本地密钥文件

1. 使用 {file:path} 读取文件内容

文件替换适合从受控文件注入密钥或共享片段：

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

路径可以相对配置文件目录、使用绝对路径，或以 ~/ 指向用户主目录。文件不存在时同样会替换为空字符串。

2. 相对路径的基准必须写清楚

下面两个配置放在不同目录时，./secrets/key 指向不同文件：

text 复制代码 
~/.config/opencode/opencode.jsonc  → ~/.config/opencode/secrets/key
/repo/opencode.jsonc              → /repo/secrets/key

团队配置不要引用仓库内的明文秘密文件。即使 .gitignore 已配置，也可能被压缩包、IDE 索引、备份或误操作带出。

3. 文件权限和轮换同样重要

在类 Unix 系统中限制文件仅供当前用户读取；Windows 应使用 ACL 限制访问主体。轮换时采用原子替换，避免进程读取到半写入内容。

bash 复制代码 
install -m 600 /dev/null "$HOME/.secrets/openai-key"
printf '%s' "$ROTATED_VALUE" > "$HOME/.secrets/openai-key.next"
chmod 600 "$HOME/.secrets/openai-key.next"
mv "$HOME/.secrets/openai-key.next" "$HOME/.secrets/openai-key"

示例中的 $ROTATED_VALUE 仅表示受控输入，生产脚本不得把值打印到日志。

八、多环境配置不要靠复制粘贴

1. 用环境变量选择少量差异

开发、测试和生产的差异如果只有模型或网关地址，可以通过启动环境注入，而不是维护三份完整配置。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "providers": {
    "openai": {
      "settings": {
        "baseURL": "{env:OPENAI_BASE_URL}",
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

环境只提供值，结构仍由受版本控制的配置决定。

2. 用启动脚本固定环境契约

为每个环境定义允许的变量、默认值和必需检查。

powershell 复制代码 
param([ValidateSet('dev','test','prod')] [string]$Stage = 'dev')

$config = @{
  dev  = @{ Model = 'openai/gpt-6.1-sol'; Url = 'https://dev-gateway.example.invalid' }
  test = @{ Model = 'openai/gpt-6.1-sol'; Url = 'https://test-gateway.example.invalid' }
  prod = @{ Model = 'openai/gpt-6.1-sol'; Url = 'https://prod-gateway.example.invalid' }
}[$Stage]

$env:OPENCODE_MODEL = $config.Model
$env:OPENAI_BASE_URL = $config.Url
if (-not $env:OPENAI_API_KEY) { throw 'Missing provider credential' }
opencode

域名使用 .invalid 保证示例不会误连真实服务。

3. 生产环境必须减少动态性

生产自动化应固定 OpenCode 版本、配置 Commit、模型标识和允许的插件集合，避免"同一流水线今天和昨天读取到不同能力"。

yaml 复制代码 
runtime_manifest:
  opencode_version: pinned
  config_commit: recorded
  model: explicit
  plugins: allowlisted
  schema_validation: required
  smoke_test: required

动态配置可以提高便利性，但每一个动态来源都应进入审计清单。

九、更新策略与版本治理

1. update 只在全局层生效

官方配置支持 disable、notify 和 auto。省略时默认 notify。项目级更新设置会被忽略，这是为了避免仓库替用户或机器决定安装行为。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "update": "notify"
}

自动安装完成后不会重启正在运行的服务器，必须手动重启才能启用新版本。

2. 团队发布要区分"下载"和"激活"

版本治理应记录四个状态：发现新版本、下载完成、服务重启、健康检查通过。

text 复制代码 
available
  → staged
  → restarted
  → smoke-tested
  → promoted

只记录"安装成功"不足以证明共享后台服务已经运行新版本。

3. 回滚前保留兼容性证据

升级前导出版本、配置摘要和关键行为基线；升级后执行相同 Smoke Test。如果失败，回滚二进制不一定能回滚已经迁移的数据或插件状态。

yaml 复制代码 
pre_upgrade:
  - record_cli_version
  - record_effective_config_sources
  - back_up_supported_state
  - run_baseline_smoke_test
post_upgrade:
  - restart_service
  - verify_version
  - run_same_smoke_test
  - compare_results

十、共享后台服务改变了配置排障方式

1. 多个客户端可能连接同一服务

OpenCode CLI 默认发现或启动当前用户共享的后台服务。TUI、Desktop 和其他本地客户端可能连接同一服务，由它持有会话、配置、集成、权限和工具执行状态。

bash 复制代码 
opencode
opencode mini
opencode run "Explain this repository"

看到多个客户端表现一致，不代表它们各自独立加载了配置；它们可能共享同一个后台进程。

2. --standalone 用于隔离验证

需要区分"配置文件问题"与"共享服务旧状态"时，可以启动私有服务进行对照。

bash 复制代码 
opencode --standalone

也可以显式连接指定服务器：

bash 复制代码 
opencode --server http://localhost:4096

地址仅为本机示例。远程服务器还需要独立处理认证、TLS 和网络边界。

3. 不要用重装代替状态定位

官方 CLI 提供 opencode debug paths 查看数据、配置、缓存、状态、日志等路径，也可以只输出某一项。

bash 复制代码 
opencode debug paths
opencode debug paths config
opencode debug paths log
opencode debug paths db

该命令不会启动服务器或打开数据库，适合在破坏现场前收集证据。

十一、配置变更的验证流水线

1. 第一道：静态解析与 Schema 校验

提交前至少验证 JSONC 可解析、Schema 无错误、禁止字段未出现、敏感值未写入。

yaml 复制代码 
config_lint:
  parse_jsonc: required
  schema_errors: 0
  plaintext_secret_patterns: 0
  experimental_keys: reviewed
  unknown_fields: 0

静态检查只能证明格式和字段形状，不能证明合并后的最终行为。

2. 第二道：来源和覆盖关系测试

在测试目录构造全局、根目录、子目录和 .opencode 四层最小配置，验证最终值与预期一致。

text 复制代码 
fixture/
├── opencode.jsonc
├── .opencode/opencode.jsonc
└── packages/web/
    ├── opencode.jsonc
    └── .opencode/opencode.jsonc

测试用字段应无副作用，例如输出上限或虚构 Agent 描述，避免误触 Provider 和外部工具。

3. 第三道：运行时 Smoke Test

在隔离环境启动 OpenCode，验证模型可解析、必需变量存在、禁止能力被拒绝、允许能力可用、日志没有明文秘密。

yaml 复制代码 
smoke_tests:
  - config_loaded
  - provider_resolved
  - allowed_tool_succeeds
  - denied_tool_is_blocked
  - formatter_runs
  - secrets_are_redacted

结果应保留退出码、版本、配置 Commit 和时间戳。

十二、配置冲突的系统化排障

1. 先列清单，不要立即改文件

从当前工作目录出发，列出所有可能被发现的直接配置和 .opencode 配置，再补充全局、系统和托管来源。

powershell 复制代码 
$cursor = (Get-Location).Path
while ($cursor) {
  @(
    (Join-Path $cursor 'opencode.json'),
    (Join-Path $cursor 'opencode.jsonc'),
    (Join-Path $cursor '.opencode/opencode.json'),
    (Join-Path $cursor '.opencode/opencode.jsonc')
  ) | Where-Object { Test-Path -LiteralPath $_ }
  $parent = Split-Path -Parent $cursor
  if ($parent -eq $cursor) { break }
  $cursor = $parent
}

脚本只列文件，不展开其中的秘密。

2. 用二分法定位冲突层

如果 --standalone 仍复现，问题更可能来自配置内容或工作目录；如果私有服务正常而共享服务异常，再检查服务版本、启动参数和状态刷新。

text 复制代码 
共享服务异常？
  ├─ standalone 也异常 → 查文件发现、变量、Schema、Provider
  └─ standalone 正常   → 查共享服务版本、连接目标、重启与缓存

不要一开始删除缓存、配置或数据库，那会同时消除证据和恢复路径。

3. 把"没生效"改写成可验证断言

"模型配置没生效"过于模糊，应改成：在目录 X、版本 Y、连接服务器 Z 时，期望默认模型 A，实际模型 B；全局、项目、系统来源分别是什么。

yaml 复制代码 
incident:
  cwd: /example/repo/packages/web
  client_version: recorded
  server_target: recorded
  expected_model: provider/model-a
  observed_model: provider/model-b
  config_sources: enumerated

可验证断言能直接映射到优先级链，而不是靠反复修改碰运气。

十三、实验配置的隔离策略

1. experimental 不应直接成为生产依赖

官方明确提示实验设置可能在任何版本中变化、失效或移除。当前实验项包括 Todo、Subagent 深度、便携 Shell 扫描器、后台压缩和位置空闲超时等。

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "todo": true,
    "subagent_depth": 2,
    "background_compaction": true,
    "location_idle_timeout": "4 hours"
  }
}

这段配置只能作为受控试验样例，不能无评审复制到生产。

2. 为每个实验项准备退出条件

试验说明至少包含目标、负责人、适用版本、影响范围、成功指标、失败阈值和回退动作。

yaml 复制代码 
experiment:
  feature: background_compaction
  owner: platform-team
  scope: pilot-repositories
  success: lower_compaction_pause_p95
  abort: rework_rate_increase_over_threshold
  rollback: remove_key_and_restart_service

没有退出条件的实验项会悄悄变成永久依赖。

3. 关注已弃用字段

官方 Config 文档已将 experimental.policies 标记为弃用，建议迁移到顶层 policies。旧字段仍可能工作，但继续新增会积累迁移债务。

jsonc 复制代码 
{
  "policies": [
    { "action": "provider.use", "resource": "approved-provider", "effect": "allow" }
  ]
}

每次升级都应扫描弃用警告，而不是等字段完全移除后再抢修。

十四、可观测性与审计

1. 记录来源，不记录秘密

配置审计应回答"从哪里加载、谁修改、何时生效、验证结果如何"，不应保存变量或文件替换后的明文。

json 复制代码 
{
  "event": "opencode.config.verified",
  "version": "pinned-version",
  "cwd_class": "repository-root",
  "sources": ["global", "project", "system"],
  "schema_errors": 0,
  "secret_values_logged": false
}

2. 建立配置健康指标

yaml 复制代码 
config_parse_success_rate: 0.999
schema_validation_failure_count: 3
missing_required_variable_count: 2
unexpected_override_incidents: 0
rollback_count: 1

只统计"启动成功率"会漏掉错误模型、错误 Provider 和安全策略未生效等静默问题。

3. 关联客户端、服务和配置版本

共享服务模式下，客户端版本和后台服务版本可能不是同一个观察点。审计记录应同时包含连接目标、客户端版本、服务版本、配置 Commit 和启动时间。

yaml 复制代码 
runtime_identity:
  client_version: recorded
  server_version: recorded
  server_url: classified
  config_revision: recorded
  process_started_at: recorded

这样才能解释"同一份配置在两台机器上结果不同"。

十五、生产落地模板与总结

1. 推荐的仓库配置骨架

jsonc 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true,
  "watcher": {
    "ignore": ["dist/**", "coverage/**", ".cache/**"]
  },
  "tool_output": {
    "max_lines": 2500,
    "max_bytes": 65536
  },
  "instructions": [
    "CONTRIBUTING.md",
    "docs/engineering/*.md"
  ],
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ]
}

模型、Provider 凭据和个人偏好留给全局层或受控运行环境；组织禁止项由系统或管理策略负责。

2. 上线检查清单

  • 已统一使用直接配置或 .opencode 配置，例外有说明；
  • 所有文件包含官方 $schema；
  • JSONC 可解析，未知字段和弃用字段已处理；
  • 已记录全局、项目、系统和托管来源；
  • 密钥只通过受控环境变量或受限文件注入；
  • 缺失变量和文件会在启动前失败；
  • 项目配置没有依赖被忽略的 update 值；
  • 普通设置、Permissions 和 Policies 分别测试；
  • 实验项有负责人、指标、版本范围和回退条件；
  • 升级后已重启共享服务并验证实际版本；
  • --standalone 对照测试已纳入排障手册；
  • 审计日志不包含密钥、文件内容和认证头；
  • 配置 Commit、客户端版本和服务版本可以关联；
  • Smoke Test 同时覆盖允许和拒绝案例；
  • 回滚方案不会删除会话、数据库或其他持久状态。

3. 总结

OpenCode v2 配置治理的核心不是记住更多字段，而是建立一条可解释的优先级链：谁拥有设置、文件从哪里发现、按什么顺序合并、变量如何注入、共享服务何时重新加载，以及最终行为怎样验证。

成熟方案应形成闭环：

text 复制代码 
所有权先明确
  → 配置来源可枚举
  → Schema 与秘密扫描先静态检查
  → 合并顺序在测试目录验证
  → 运行时用 standalone 和共享服务双向对照
  → 更新、实验项和策略独立治理
  → 最终以版本、Commit、退出码和行为证据验收

当这条链路稳定后，"明明改了为什么不生效"就不再是一场猜测，而是一个可以从来源、优先级、连接目标和运行证据逐层定位的工程问题。

参考资料：

本文依据 2026 年 10 月 29 日可见的 OpenCode v2 官方文档整理。配置字段、实验项、Schema、策略动作和共享服务行为可能继续变化；生产环境应固定实际版本，并以当前 Schema、官方文档和运行结果为准。

相关推荐
杨杨杨大侠17 分钟前
AI 怎么知道自己改对了？从 Astra 修千问说到 Harness²
人工智能·agent
tellmewhoisi20 分钟前
深度学习39:RNN基础介绍,api参数解惑和代码api
人工智能·rnn·深度学习
金融Tech趋势派35 分钟前
企业微信客户管理工具哪个好？按企业规模、行业与合规要求的三层判断标准
人工智能·企业微信
组工部管理能手李哥37 分钟前
一次政务知识库体验：AI回答之外，我更在意那行引用来源
大数据·人工智能·大模型·政务
硅谷秋水1 小时前
AgenticRoboRL：将“编程智能体”后训练引入智能体化机器人领域
人工智能·机器学习·语言模型·机器人
武天旭1 小时前
AI安全--AI大模型的毒性偏见与安全对齐实践
人工智能·python·深度学习
wordbaby1 小时前
构建高效的智能体（Building Effective Agents）— Anthropic 官方全文精译与图解
人工智能
xsd202411181 小时前
AI 短剧怎么做？
人工智能
m0_715674431 小时前
政务泛监测体系能力排行：AI 重塑监测边界，治理的颗粒度革命
大数据·网络·人工智能·安全·网络安全·政务
山东科恩光电1 小时前
安全触边在智能制造产线自动化设备防夹伤防护中的选型与应用实践
安全
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03几个好用的ip纯净度检测网站04GitHub 镜像站点05昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07苹果iPA游戏软件资源下载网站08如何新建文件夹？ 电脑新建文件夹的4种方法09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10Dify：一站式AI应用开发平台全解析与Windows部署指南