OpenCode 会把 Provider、凭据、项目覆盖、规则、插件和会话保存在不同位置。即使 OcHub 中已经 存在一张 Provider 卡片，只要其中一个标识或配置层不匹配，它仍可能无法使用。
全局配置只是第一层
OcHub 管理全局 ~/.config/opencode/opencode.json。OpenCode 会把它与远程组织默认值、
OPENCODE_CONFIG、项目 opencode.json、运行时内联配置和受管策略合并。靠后的来源与受管
设置可以覆盖同名键，无冲突的键仍会保留。
.opencode/ 目录还是 Agent、命令、插件、技能和工具的来源。它不需要替换 Provider 条目，
也能改变 Agent 最终选择的模型或行为。
OcHub 预览正确、OpenCode 却显示另一个 Provider 或模型时：
- 从发生问题的相同目录启动 OpenCode。
- 向上检查项目
opencode.json与.opencode/扩展。 - 检查
OPENCODE_CONFIG、OPENCODE_CONFIG_CONTENT和受管设置。 - 注意
OPENCODE_CONFIG_DIR会增加另一套扩展目录。 - 添加
"$schema": "https://opencode.ai/config.json"获得编辑器校验。
覆盖一个嵌套值，并不一定删除其他层继承的无关值。
Provider ID 把凭据与配置连接起来
/connect 会把凭据单独保存在 ~/.local/share/opencode/auth.json。在 /connect 输入的
Provider ID 必须与 opencode.json 中 provider.<id> 的键完全一致。
常见的“只配了一半”状态包括：
- Provider 出现在
/models，但不存在匹配凭据。 - 凭据存在，但 ID 的大小写、标点或拼写不同。
- OcHub 写入了
options.apiKey，同时还残留旧的/connect凭据，导致排障来源不明确。
先运行 opencode auth list，再核对 Provider ID、配置条目和凭据来源。不要提交 auth.json
或明文 Authorization header。OcHub 的内联 API Key 适合本机切换；仓库需要安全引用密钥时，
应手工使用 {env:NAME} 或 {file:path}。
未设置的 {env:NAME} 会被替换为空字符串，因此配置可以语法正确，却用空值鉴权。
AI SDK 包决定线上协议
“OpenAI-compatible”并不是单一协议：
| 上游端点 | OpenCode 包 |
|---|---|
/v1/chat/completions |
@ai-sdk/openai-compatible |
/v1/responses |
@ai-sdk/openai |
| Anthropic Messages | @ai-sdk/anthropic |
| Amazon Bedrock | @ai-sdk/amazon-bedrock |
| Google Gemini | @ai-sdk/google |
给 Responses-only 模型选择 @ai-sdk/openai-compatible 时，Provider 与模型可能正常显示，
直到真正发送消息才失败。只修改 baseURL 同样不会把 Chat 转成 Responses。
当前 OpenCode 可在混合 Provider 中按模型覆盖包。OcHub 表单提供 Provider 级包选择，并在 编辑时保留原生的模型扩展字段；依赖手工混合配置前应仔细检查 JSON 预览。
模型元数据会影响上下文行为
models 下的键是 OpenCode 选择的模型 ID，name 只是显示文字。limit.context 和
limit.output 告诉 OpenCode 模型接受的输入与输出上限，不会扩大上游真实限制。
错误的 limit 可能导致过早压缩，或让服务器拒绝过大的请求。应使用模型供应商公布的真实 Token 限制。Models.dev 已覆盖的标准 Provider，不要无理由覆写。
OcHub 的“选项扩展”会把 true、false 和数字解析为原生 JSON 类型，其余文字保留为字符串。
SDK 选项对类型敏感时必须检查预览。
AGENTS.md 与 CLAUDE.md 是二选一回退
OpenCode 优先使用项目 AGENTS.md；只有该类别没有 AGENTS.md 时才回退到 CLAUDE.md。
全局 OpenCode 与 Claude 指令文件也采用类似回退。
与 Claude Code 不同，OpenCode 不会自动展开 AGENTS.md 内的 @file 引用。复用文件应放入
instructions 数组，它支持路径、glob 和远程 URL。远程指令依赖网络且拉取超时较短，因此
关键构建规则应保留在本地。
OpenCode 默认也会加载 Claude 兼容技能。兼容层产生重复或意外指令时，可使用官方记录的
OPENCODE_DISABLE_CLAUDE_CODE* 环境变量关闭相应来源。
会话分享会发布对话
/share 会生成链接，并把对话同步到 OpenCode 服务器。任何拿到链接的人都能访问共享对话。
在 /unshare 删除前，共享内容包括完整历史与会话元数据。
专有仓库建议配置：
{
"$schema": "https://opencode.ai/config.json",
"share": "disabled"
}没有明确团队策略时不要开启 "auto"；它会自动分享每个新会话。
插件与 OMO 改变的不只是模型
OpenCode 插件可以增加 Agent、命令、Hook 和 Provider 行为。标准 OMO 与 OMO Slim 不应同时 启用。通过 OcHub 禁用任一变体前：
- 读取检测到的 OMO 状态。
- 备份 OpenCode 配置目录。
- 检查
plugin数组与项目级配置。 - 重启 OpenCode，确认当前 Agent 与 Provider。
Provider 请求问题也可能来自插件或 Agent 覆盖，而不是 provider 对象本身。
分清本地状态位置
当前常见位置：
~/.config/opencode/opencode.json：OcHub 管理的全局配置。~/.local/share/opencode/auth.json：/connect凭据。~/.local/share/opencode/opencode.db：OpenCode 与 OcHub 用量同步使用的当前会话数据库。
XDG_DATA_HOME 与 OPENCODE_DB 可以移动数据或数据库位置。OcHub 的自定义配置目录只改变
配置路径，不一定改变数据目录。手工迁移前应同时备份两处。
官方参考
- OpenCode 配置
- OpenCode Provider 与凭据
- OpenCode 规则与 AGENTS.md
- OpenCode 会话分享
OcHub 合并行为、OMO 控制、会话同步与自定义目录描述的是 OcHub 当前实现。