跳到正文
OcHub

OpenCode 进阶与易踩坑

理解配置合并、Provider 凭据、AI SDK 协议适配、规则、会话分享与本地状态。

更新于 查看 Markdown
For humans

OpenCode 会把 Provider、凭据、项目覆盖、规则、插件和会话保存在不同位置。即使 OcHub 中已经 存在一张 Provider 卡片,只要其中一个标识或配置层不匹配,它仍可能无法使用。

全局配置只是第一层

OcHub 管理全局 ~/.config/opencode/opencode.json。OpenCode 会把它与远程组织默认值、 OPENCODE_CONFIG、项目 opencode.json、运行时内联配置和受管策略合并。靠后的来源与受管 设置可以覆盖同名键,无冲突的键仍会保留。

.opencode/ 目录还是 Agent、命令、插件、技能和工具的来源。它不需要替换 Provider 条目, 也能改变 Agent 最终选择的模型或行为。

OcHub 预览正确、OpenCode 却显示另一个 Provider 或模型时:

  1. 从发生问题的相同目录启动 OpenCode。
  2. 向上检查项目 opencode.json 与 .opencode/ 扩展。
  3. 检查 OPENCODE_CONFIG、OPENCODE_CONFIG_CONTENT 和受管设置。
  4. 注意 OPENCODE_CONFIG_DIR 会增加另一套扩展目录。
  5. 添加 "$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 禁用任一变体前:

  1. 读取检测到的 OMO 状态。
  2. 备份 OpenCode 配置目录。
  3. 检查 plugin 数组与项目级配置。
  4. 重启 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 的自定义配置目录只改变 配置路径,不一定改变数据目录。手工迁移前应同时备份两处。

官方参考

OcHub 合并行为、OMO 控制、会话同步与自定义目录描述的是 OcHub 当前实现。

Navigation

Type to search…

↑↓ navigate↵ selectEsc close