---
title: "OpenCode 进阶与易踩坑"
description: "理解配置合并、Provider 凭据、AI SDK 协议适配、规则、会话分享与本地状态。"
version: "zh"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/zh/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode 进阶与易踩坑

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` 删除前，共享内容包括完整历史与会话元数据。

专有仓库建议配置：

```json
{
  "$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 的自定义配置目录只改变
配置路径，不一定改变数据目录。手工迁移前应同时备份两处。

## 官方参考

- OpenCode [配置](https://opencode.ai/docs/config)
- OpenCode [Provider 与凭据](https://opencode.ai/docs/providers)
- OpenCode [规则与 AGENTS.md](https://opencode.ai/docs/rules/)
- OpenCode [会话分享](https://opencode.ai/docs/share/)

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

Source: https://docs.ochub.org/zh/opencode/advanced/index.mdx