OpenCode 使用指南

OpenCode 是一款在终端中运行的 CLI + TUI AI 编程代理工具，也提供 IDE 插件集成。你可以将 OpenCode 指向 cch 作为统一入口来接入 Claude、GPT 与 Gemini 等模型。

macOS

安装 opencode

在 macOS 上可以选择以下任一种方式安装 OpenCode：

方式一：官方安装脚本

执行以下命令安装最新版：

curl -fsSL https://opencode.ai/install | bash

方式二：Homebrew

也可以使用 Homebrew 安装：

brew install anomalyco/tap/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

方式四：Bun

如果你使用 Bun，也可以全局安装：

bun add -g opencode-ai

连接 cch 服务

配置 opencode.json

配置文件路径：

~/.config/opencode/opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.4",
  "small_model": "openai/gpt-5.4-small",
  "provider": {
    "cchClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "cchGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.4": {
          "name": "GPT-5.4",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        },
        "gpt-5.4-small": {
          "id": "gpt-5.4",
          "name": "GPT-5.4 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        }
      }
    },
    "cchGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via cch",
      "options": {
        "baseURL": "当前站点地址/v1beta",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 cch 后台创建 API Key，并设置环境变量 CCH_API_KEY

cchClaude/openai 使用当前站点地址/v1，cchGemini 使用 ${resolvedOrigin}/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.4 或 cchClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

cd /path/to/your/project
opencode

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

 检查安装路径并添加到 PATH（例如 ~/.local/bin 或 npm 全局目录）
npm config get prefix

 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 连接失败

 检查环境变量
echo $CCH_API_KEY

 测试网络连接
curl -i 当前站点地址/v1/messages

3. 更新 opencode

npm install -g opencode-ai

Windows

安装 opencode

Windows 推荐使用包管理器（Chocolatey/Scoop），也可以使用 npm：

方式一：Chocolatey

使用 Chocolatey 安装：

choco install opencode

方式二：Scoop

使用 Scoop 安装：

scoop bucket add extras
scoop install extras/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

提示：官方说明 Windows 上通过 Bun 安装仍在推进。建议使用 Chocolatey/Scoop/npm，或从 GitHub Releases 下载二进制。

连接 cch 服务

配置 opencode.json

配置文件路径：

%USERPROFILE%\.config\opencode\opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.4",
  "small_model": "openai/gpt-5.4-small",
  "provider": {
    "cchClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "cchGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.4": {
          "name": "GPT-5.4",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        },
        "gpt-5.4-small": {
          "id": "gpt-5.4",
          "name": "GPT-5.4 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        }
      }
    },
    "cchGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via cch",
      "options": {
        "baseURL": "当前站点地址/v1beta",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 cch 后台创建 API Key，并设置环境变量 CCH_API_KEY

cchClaude/openai 使用当前站点地址/v1，cchGemini 使用 ${resolvedOrigin}/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.4 或 cchClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

cd C:\path\to\your\project
opencode

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

如果使用 npm 安装，请确保 npm 全局路径已添加到系统 PATH
重新打开终端窗口后再试

2. API 连接失败

 检查环境变量
echo $env:CCH_API_KEY

 测试网络连接
Test-NetConnection -ComputerName 当前站点地址 -Port 443

3. 更新 opencode

npm install -g opencode-ai

Linux

安装 opencode

在 Linux 上可以选择以下任一种方式安装 OpenCode：

方式一：官方安装脚本

执行以下命令安装最新版：

curl -fsSL https://opencode.ai/install | bash

方式二：Homebrew

也可以使用 Homebrew 安装：

brew install anomalyco/tap/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

方式四：Bun

如果你使用 Bun，也可以全局安装：

bun add -g opencode-ai

方式五：Paru（Arch Linux）

如果你使用 Arch Linux，也可以通过 paru（AUR）安装：

paru -S opencode-bin

连接 cch 服务

配置 opencode.json

配置文件路径：

~/.config/opencode/opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.4",
  "small_model": "openai/gpt-5.4-small",
  "provider": {
    "cchClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "cchGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via cch",
      "options": {
        "baseURL": "当前站点地址/v1",
        "apiKey": "{env:CCH_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.4": {
          "name": "GPT-5.4",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        },
        "gpt-5.4-small": {
          "id": "gpt-5.4",
          "name": "GPT-5.4 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": [
              "reasoning.encrypted_content"
            ]
          }
        }
      }
    },
    "cchGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via cch",
      "options": {
        "baseURL": "当前站点地址/v1beta",
        "apiKey": "{env:CCH_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 cch 后台创建 API Key，并设置环境变量 CCH_API_KEY

cchClaude/openai 使用当前站点地址/v1，cchGemini 使用 ${resolvedOrigin}/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.4 或 cchClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

cd /path/to/your/project
opencode

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

 检查安装路径并添加到 PATH（例如 ~/.local/bin 或 npm 全局目录）
npm config get prefix

 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API 连接失败

 检查环境变量
echo $CCH_API_KEY

 测试网络连接
curl -i 当前站点地址/v1/messages

3. 更新 opencode

npm install -g opencode-ai