# opencode-provider-switch (`ocswitch`)

English README: `README_EN.md`

`ocswitch` 是 OpenCode Provider Switch CLI，给 OpenCode 使用的本地代理。

它解决的问题很简单：

- 你在 OpenCode 里只使用一个稳定的模型名，例如 `ocswitch/gpt-5.4`
- `ocswitch` 在本地把这个别名映射到多个上游 `provider/model`
- 按你配置的顺序依次尝试上游
- 如果主上游在响应开始前失败，自动切到下一个上游

当前实现只支持 OpenAI Responses 协议，也就是 `POST /v1/responses`，并且支持流式响应。

## 适合什么场景

- 你有多个 OpenAI 兼容上游
- 你不想在 OpenCode 里频繁切换 provider 或模型入口
- 你希望用一个固定别名承接多个备用上游
- 你希望失败切换行为是确定的、可预期的

## 当前能力

- 本地维护 `ocswitch` 配置文件：上游 provider、alias、监听地址
- 支持手动添加 provider，并自动发现其 `/v1/models` 模型列表
- 支持从 OpenCode 配置导入 `@ai-sdk/openai` 自定义 provider
- 支持创建 alias，并按顺序绑定多个上游 target
- 支持把 alias 同步到 OpenCode 的 `provider.ocswitch.models`
- 支持本地代理 `POST /v1/responses`
- 支持流式透传
- 支持首字节前失败切换
- 返回调试响应头，便于确认这次请求实际落到了哪个上游

## 不支持的内容

- Anthropic 原生协议
- 多协议路由
- 自动按延迟、价格、提示词类型选路
- 中途流式拼接切换
- SQLite、管理后台、计费统计
- 完整接管 OpenCode 所有配置层
- 从 `auth.json` 自动导入 provider 定义

## 安装

```bash
go build -o ocswitch ./cmd/ocswitch
```

如果你只想临时运行，也可以直接：

```bash
go run ./cmd/ocswitch --help
```

## 5 分钟快速上手

### 1. 添加上游 provider

`ocswitch` 要求上游是 OpenAI 兼容接口，并且 `--base-url` 需要带上 `/v1`。默认会自动调用上游 `/v1/models` 拉取模型列表并缓存到本地配置，后续绑定 alias 时可用于校验模型名、减少手写 typo；如果发现失败，只会输出 warning，不会阻止连接信息保存。如果某些 provider 不开放该接口，可以显式加 `--skip-models` 仅保存连接信息。
```bash
ocswitch provider add --id su8 --base-url https://cn2.su8.codes/v1 --api-key sk-xxx
ocswitch provider add --id codex --base-url https://api-vip.codex-for.me/v1 --api-key sk-yyy
```

如果某个上游还需要额外请求头，可以重复传 `--header`：

```bash
ocswitch provider add \
  --id relay \
  --base-url https://example.com/v1 \
  --api-key sk-zzz \
  --header "X-Custom-Token=abc" \
  --header "X-Workspace=my-team"
```

如果你之后想把这些额外 header 全部清空，可以显式传：

```bash
ocswitch provider add --id relay --base-url https://example.com/v1 --clear-headers --skip-models
```

查看当前 provider：

```bash
ocswitch provider list
```

### 2. 创建 alias，并绑定多个上游 target

下面这个例子表示：当你使用 `ocswitch/gpt-5.4` 时，优先走 `su8/gpt-5.4`，失败后再走 `codex/GPT-5.4`。推荐在未传 `--provider` 时直接把上游 target 写成 `Provider/Model`；旧的 `--provider` + `--model` 写法仍然保留作为兼容兜底，而且 `model` 本身即使包含 `/` 也不会被强行改判。

```bash
ocswitch alias add --name gpt-5.4 --display-name "GPT 5.4"
ocswitch alias bind --alias gpt-5.4 --model su8/gpt-5.4
ocswitch alias bind --alias gpt-5.4 --model codex/GPT-5.4
```
查看当前 alias：

```bash
ocswitch alias list
```

注意：

- target 的顺序就是失败切换顺序
- enabled alias 必须至少有一个可路由 target
- `ocswitch alias bind` 在 alias 不存在时会自动创建一个 enabled alias

### 3. 先做一次静态检查

```bash
ocswitch doctor
```

`ocswitch doctor` 只做静态校验，不会真的请求上游，不会消耗额度。

它会检查：

- 本地 `ocswitch` 配置能不能正常加载
- alias 是否引用了不存在的 provider
- enabled alias 是否至少有一个可路由 target
- 本地代理监听地址是否合理
- 默认会同步到哪个 OpenCode 配置文件

### 4. 把 alias 同步到 OpenCode

```bash
ocswitch opencode sync
```

这个命令会做一件事：把当前可路由的 alias 列表同步进 OpenCode 的 `provider.ocswitch.models`。

注意：如果目标文件原本是 JSONC，`sync` 写回时会规范化成普通 JSON，因此注释和尾逗号不会保留。
默认行为：

- 优先复用全局 OpenCode 配置文件：`opencode.jsonc` > `opencode.json` > `config.json`
- 如果都不存在，就创建 `~/.config/opencode/opencode.jsonc`
- 默认目标明确只看全局用户配置目录，不跟随 `OPENCODE_CONFIG_DIR`
- 只更新 `provider.ocswitch`
- 不会修改顶层 `model`
- 不会修改顶层 `small_model`

如果你希望顺手把默认模型也切到 `ocswitch`，需要显式指定：

```bash
ocswitch opencode sync --set-model ocswitch/gpt-5.4
```

如果你还有小模型 alias，也可以这样：

```bash
ocswitch opencode sync \
  --set-model ocswitch/gpt-5.4 \
  --set-small-model ocswitch/gpt-5.4-mini
```

先预览不写入：

```bash
ocswitch opencode sync --dry-run
```

写到指定 OpenCode 配置文件：

```bash
ocswitch opencode sync --target /path/to/opencode.jsonc
```

### 5. 启动本地代理

```bash
ocswitch serve
```

默认监听地址：

- `127.0.0.1:9982`
- 本地 API Key：`ocswitch-local`

启动后，本地代理地址是：

```text
http://127.0.0.1:9982/v1
```

### 6. 在 OpenCode 里使用

完成 `ocswitch opencode sync` 后，你应该能在 OpenCode 里看到 `ocswitch/<alias>`。

例如：

- `ocswitch/gpt-5.4`

如果你执行了：

```bash
ocswitch opencode sync --set-model ocswitch/gpt-5.4
```

那么 OpenCode 默认模型也会直接切到这个 alias。

## 直接验证本地代理

如果你想先不走 OpenCode，直接验证 `ocswitch` 是否能正常代理，可以自己发一个请求：

```bash
curl -sN -X POST http://127.0.0.1:9982/v1/responses \
  -H "Authorization: Bearer ocswitch-local" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","stream":true,"input":"hello"}'
```

注意这里请求体里的 `model` 可以直接写 alias 本身，例如 `gpt-5.4`；也兼容 `ocswitch/gpt-5.4` 这种带前缀的写法。

因为 `ocswitch/gpt-5.4` 是 OpenCode 侧常见的模型选择写法；真正路由到本地时，工具会统一解析成 alias 自身。

## 从现有 OpenCode 配置导入 provider

如果你原来已经在 OpenCode 里配置过一些自定义 provider，可以直接导入：

```bash
ocswitch provider import-opencode
```

或者指定导入源：

```bash
ocswitch provider import-opencode --from ./examples/opencode.jsonc
```

支持范围只有这一类：

- `npm: @ai-sdk/openai`
- 有 `options.baseURL`
- `options.apiKey` 可以为空；当前静态校验不会单独拦截空上游 API Key，这类问题通常会在真实请求上游时暴露
注意：

- 这不是完整迁移工具
- 默认导入源也只看全局用户配置目录，不跟随 `OPENCODE_CONFIG_DIR`
- 如果你要导入别的 OpenCode 配置文件，请显式传 `--from`
- 导入时仍要求 `baseURL` 满足 `/v1` 约束；不合法的 provider 会被跳过
- 如果源 OpenCode 配置已经声明 `models`，导入时会一并保留，但这类导入值默认只作为展示/迁移信息，不会像主动发现到的 catalog 那样做硬校验
- 如果你修改了 provider 的连接信息，但本次 discovery 被跳过、失败或返回空列表，旧 catalog 会降级成“不可信元数据”：仍保留在配置里，但不会继续用于强校验
- 如果你的 provider 不开放 `/v1/models`，后续可用 `ocswitch provider add --skip-models ...` 仅保存连接信息
- `--overwrite` 会更新导入到的基本连接信息，但仍保留本地的 disabled 状态、额外 header，以及仍然可信的 discovered catalog
- 如果你的旧配置依赖额外自定义 header，首次导入后仍可能需要自己用 `ocswitch provider add --header ...` 补齐
- `ocswitch` 自己不会被反向导入

覆盖已存在的 provider：

```bash
ocswitch provider import-opencode --overwrite
```

## 常用命令

### provider

添加或更新 provider：

```bash
ocswitch provider add --id <id> --base-url <url-with-/v1> --api-key <key>
ocswitch provider add --id <id> --base-url <url-with-/v1> --api-key ""
ocswitch provider add --id <id> --base-url <url-with-/v1> --clear-headers
ocswitch provider add --id <id> --base-url <url-with-/v1> --skip-models
```

如果你需要把已保存的上游 API key 清空，显式传 `--api-key ""` 即可。
如果你需要把已保存的额外 header 清空，显式传 `--clear-headers` 即可。

查看 provider：

```bash
ocswitch provider list
```

禁用 provider：

```bash
ocswitch provider disable <id>
```

重新启用 provider：

```bash
ocswitch provider enable <id>
```

删除 provider：

```bash
ocswitch provider remove <id>
```

注意：删除 provider 不会自动帮你清理 alias 里的引用。引用还在的话，`ocswitch doctor` 会报错。

### alias

创建或更新 alias：

```bash
ocswitch alias add --name <alias>
```

给 alias 追加一个 target：

```bash
ocswitch alias bind --alias <alias> --model <provider-id>/<upstream-model>
ocswitch alias bind --alias <alias> --provider <provider-id> --model <upstream-model>
```

解绑 target：

```bash
ocswitch alias unbind --alias <alias> --model <provider-id>/<upstream-model>
ocswitch alias unbind --alias <alias> --provider <provider-id> --model <upstream-model>
```

查看 alias：

```bash
ocswitch alias list
```

删除 alias：

```bash
ocswitch alias remove <alias>
```

### 其他

静态检查：

```bash
ocswitch doctor
```

启动代理：

```bash
ocswitch serve
```

同步到 OpenCode：

```bash
ocswitch opencode sync
```

全局帮助：

```bash
ocswitch --help
ocswitch provider --help
ocswitch alias --help
ocswitch opencode sync --help
```

## 配置文件说明

本地 `ocswitch` 配置文件默认路径：

- 如果设置了 `OCSWITCH_CONFIG`，优先使用它
- 否则使用 `$XDG_CONFIG_HOME/ocswitch/config.json`
- 再否则使用 `~/.config/ocswitch/config.json`

也可以对每个命令显式指定：

```bash
ocswitch --config /path/to/config.json doctor
```

命令级行为、默认值、写入范围与副作用，以对应命令的 `--help` 为准；README 主要保留快速上手与背景说明。

一个最小配置示例：

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 9982,
    "api_key": "ocswitch-local"
  },
  "providers": [
    {
      "id": "su8",
      "name": "SU8",
      "base_url": "https://cn2.su8.codes/v1",
      "api_key": "sk-xxx"
    },
    {
      "id": "codex",
      "name": "Codex",
      "base_url": "https://api-vip.codex-for.me/v1",
      "api_key": "sk-yyy",
      "disabled": true
    }
  ],
  "aliases": [
    {
      "alias": "gpt-5.4",
      "display_name": "GPT 5.4",
      "enabled": true,
      "targets": [
        {
          "provider": "su8",
          "model": "gpt-5.4",
          "enabled": true
        },
        {
          "provider": "codex",
          "model": "GPT-5.4",
          "enabled": true
        }
      ]
    }
  ]
}
```

## 失败切换规则

`ocswitch` 的切换规则很保守，也很容易理解。

会切换到下一个 target 的情况：

- 连接失败
- DNS / 网络错误
- 上游在返回首字节前超时或断开
- 上游返回 `429`
- 上游返回 `5xx`

不会切换的情况：

- alias 不存在
- alias 被禁用
- alias 没有可用 target
- 上游返回 `400`
- 上游返回 `401`
- 上游返回 `403`
- 上游返回 `404`
- 响应已经开始向客户端写出后才出错

重点是：

- 只有在“还没向下游写出任何字节”之前，才允许切换
- 一旦开始向客户端输出流，当前上游就锁定了
- 不支持中途把一半流接到另一个 provider 上继续输出

## 调试响应头

当请求已经选定某个上游并开始向客户端返回该次尝试的结果时，响应里会附带这些头：

- `X-OCSWITCH-Alias`
- `X-OCSWITCH-Provider`
- `X-OCSWITCH-Remote-Model`
- `X-OCSWITCH-Attempt`
- `X-OCSWITCH-Failover-Count`

你可以用它们确认：

- 本次请求命中了哪个 alias
- 实际走了哪个 provider
- 实际转发成了哪个上游 model
- 这是第几次尝试
- 前面已经失败切换过几次

## 常见问题

### 为什么 `opencode models` 里看不到 `ocswitch/<alias>`？

先检查这几件事：

1. 你是否执行过 `ocswitch opencode sync`
2. 你的 alias 是否是 enabled 状态
3. alias 是否至少绑定了一个可路由 target
4. alias 绑定的 provider 是否都被禁用了
5. OpenCode 当前实际使用的配置文件，是否就是 `ocswitch opencode sync` 写入的那个文件
6. 执行一次 `ocswitch doctor`，看输出里的 `opencode config target`

### 为什么 `ocswitch doctor` 报 alias 没有可用 target？

因为当前实现要求：只要 alias 是 enabled，就必须至少有一个可路由的 target。

可路由的意思是同时满足：

- target 自己是 enabled
- target 引用的 provider 存在且没有被禁用

你可以：

- 给它绑定 target
- 重新启用被禁用的 provider
- 或者把这个 alias 改成 disabled 后再保存

### 为什么要禁用 provider，而不是把 alias target 也改成 disabled？

因为 provider 可能被多个 alias 复用。

`ocswitch provider disable` 只会让路由层在 failover 时自动跳过这个 provider，不会改写 alias 里的 target 状态，这样重新启用 provider 时不会和 alias 上原有的启用关系打架。

### 删除 provider 后为什么还有报错？

因为 alias 里的 target 还是旧引用。需要继续执行：

```bash
ocswitch alias unbind --alias <alias> --model <provider-id>/<model>
ocswitch alias unbind --alias <alias> --provider <provider-id> --model <model>
```

### 本地代理鉴权是什么？

默认是静态 key：

```text
ocswitch-local
```

OpenCode 在 `provider.ocswitch.options.apiKey` 里会使用这个值。直接手工请求本地代理时，也要带上这个 key。

## 安全说明

- 默认只监听 `127.0.0.1`
- 上游凭据保存在本地 `ocswitch` 配置文件中
- 本项目当前没有做多用户或远程网络安全保证

所以请把本地配置文件当成敏感文件处理。

## 英文版 README

原英文版文档已保存在：

- `README_EN.md`