OpenCode 安装与 OmniProxy 配置

OpenCode 是开源的编码助手，可以在终端、IDE 或桌面里写代码，也不会保存你的代码和上下文，适合在意隐私的项目中使用。build 用来修改项目，plan 默认只读，适合先看懂不熟悉的代码、整理改法。模型服务可以按你的需要选择。

安装前准备

安装脚本是最省事的方式。你需要一个现代终端，也就是可以运行命令、操作项目文件的终端程序，例如 WezTerm、Alacritty、Ghostty 或 Kitty。Windows 上优先使用 WSL，它是在 Windows 中运行 Linux 环境的工具，性能和功能更完整。

最容易

安装脚本

• curl opencode.ai/install
• macOS Linux 直接用
• Windows 建议 WSL

macOS Linux

Homebrew tap

• anomalyco/tap/opencode
• 比公式更新更勤
• Arch 也有软件包

Windows 本机

包管理器

• choco 或 scoop
• 或 npm 全局安装
• 也可下 Releases

同时准备好当前模型列表里的模型 ID。模型 ID 就是服务用来准确识别某个模型的名称。

安装并首次启动

最容易使用的安装命令是：

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

也可以使用下面这些安装方式：

• Node.js：npm install -g opencode-ai。Bun、pnpm、Yarn 也有对应的全局安装命令，见文末的介绍页。
• macOS 和 Linux 的 Homebrew：brew install anomalyco/tap/opencode。用这个 tap，它比 Homebrew 团队维护的 brew install opencode 更新更勤。
• Arch Linux：稳定版 sudo pacman -S opencode，较新版本可以用 AUR 的 opencode-bin。
• Windows：choco install opencode 或 scoop install opencode，也可以 npm install -g opencode-ai。官方还写了可以从 Releases 下载二进制文件。用 Bun 在 Windows 上安装的支持仍在进行中。

进入你的项目目录，然后启动 OpenCode：

cd /path/to/project
opencode

第一次使用时可以运行 /init。它会分析项目，并在项目根目录创建 AGENTS.md。这个文件可以提交进 Git，方便项目保留这份说明。

从 OmniProxy 取得连接参数

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: 从 OmniProxy 当前模型列表复制

baseURL 是服务地址，API Key 是访问凭证，Model ID 是模型的完整名称。

走 /v1/chat/completions 时，npm 包用 @ai-sdk/openai-compatible。这里的 Chat Completions 是一种聊天请求接口。只有模型走 /v1/responses 时才改用 @ai-sdk/openai。OmniProxy 按聊天补全路径使用时，保留兼容包。

模型 ID 从 OmniProxy 当前列表整段复制，斜杠也保留。2026-10-09 的两个对照 ID 是 claude-sonnet-5-5 和 gpt-6-luna。gpt-6-luna 支持 Chat Completions；函数调用在 Chat Completions 里只在 reasoning_effort 为 none 时支持。列表里没有的 ID 不要照抄。

填写工具配置

Provider 可以理解为 OpenCode 连接模型服务时使用的一组配置。Provider 文档把「/connect 列表里没有的 OpenAI 兼容服务」写成自定义 Provider。OpenAI 兼容服务，就是使用相同请求格式、可以被同一类客户端调用的服务。

1. 在 OpenCode 里运行 /connect，滚动到 Other。
2. 输入一个 Provider ID。下文用 omniproxy。这个 ID 要好记，因为配置文件里要使用同一个。
3. 输入 OmniProxy 的 API Key。这一步只保存凭证，地址和模型还要写进 opencode.json。凭证保存在 ~/.local/share/opencode/auth.json。
4. 在项目目录创建或修改 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. 运行 /models，自定义 Provider 和模型会出现在列表里。

/connect 里的 ID 必须和 opencode.json 里的键一致。不要把真实密钥写进这个文件。如果不用 /connect，也可以在 options.apiKey 里用环境变量写法，例如 {env:变量名}。2026-10-09 用 OpenCode 1.18.34，把密钥直接写在项目的 options.apiKey 里，没有走 /connect，也能连上。网关不校验密钥时，这一项可以是一串只在本机使用的占位字符。models 里的键使用列表中的完整 ID。

密钥

/connect

• 选最下面的 Other
• Provider ID 自定
• 存在 auth.json

项目

opencode.json

• provider 键要同名
• npm 用兼容包
• baseURL 以 /v1 结束

选用

/models

• 列表里出现模型
• 选一个再提问
• ID 以网关列表为准

验证一个真实任务

在项目目录里先运行一次真实任务。模型引用格式是 Provider ID/模型 ID，模型 ID 里的斜杠要保留：

opencode run --model omniproxy/claude-sonnet-5-5 --auto "说明一个你指定的文件在做什么，不要改文件。"

--auto 会让这次运行可以使用读文件等工具。2026-10-09 用 OpenCode 1.18.34 读到了指定文件的内容。第一次大约两分钟。

交互使用方式是运行 opencode，再用 /models 选中模型。官方用法里可以用 @ 搜索文件。可以用 opencode auth list 确认通过 /connect 记下的凭证，然后在 OmniProxy 的调用记录里确认来源和模型 ID。

启动

opencode 能开

• 先 cd 到项目
• auth list 能看到 ID
• 配置文件在项目里

任务

它读了代码

• 问一个具体文件
• 看它的说明
• 不对就 /undo

记录

网关看得到

• 来源是 OpenCode
• 模型 ID 一致
• 不要提交密钥

常见错误

• /models 里没有 OmniProxy：检查 /connect 的 ID 和 opencode.json 的键是否一致，npm 是否为 @ai-sdk/openai-compatible，baseURL 是否以 /v1 结束。
• 凭证不见了：运行 opencode auth list。Bedrock 这类靠环境变量的 Provider 不会出现在这里；自定义 Provider 走 /connect 时应该看得到。
• Windows 功能不完整：改用 WSL 里的安装脚本。
• 模型 ID 无效：从 OmniProxy 当前列表重新复制，并改 models 里的键。
• 请求走错接口：聊天补全保持 @ai-sdk/openai-compatible。不要为了 Responses 接口改包，除非 OmniProxy 上的这个模型确实走 /v1/responses。

官方参考

安装见 OpenCode 介绍。自定义 Provider 见 Providers。举例用的模型 ID 见 Claude 模型总览 和 GPT-6 Luna。

用你自己的 OmniProxy 配置替换每个占位符。不要发布真实密钥。

保存成功或 HTTP 200 不单独等同完整 Agent 兼容。请在 OmniProxy 调用记录中确认来源和模型。

官方来源 · OpenCode ↗