使用文档

OpenCode 安装与配置指南

从安装命令到首次对话，理解客户端、模型提供商和项目规则各自负责什么。

本站是独立使用指南，不是 OpenCode 官方网站。内容核对日期：2026 年 10 月 20 日；版本行为以官方文档为准。

先确认版本

OpenCode 1 和 OpenCode 2 使用同一个 opencode 命令，默认不能并行安装。以下基础命令参考 OpenCode 1 文档；升级或迁移前先查看OpenCode 2 文档，避免覆盖现有安装。

安装 CLI 并启动

选择一种安装方式即可。运行远程安装脚本前，请确认来源并检查脚本内容。

npm

npm install -g opencode-ai

官方安装脚本

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

进入自己的项目目录，执行 opencode --version 确认版本，再执行 opencode 启动。桌面版与各系统下载请查看下载说明。

opencode init 与 /init 有什么区别？

搜索“opencode init”时，通常想找的是 TUI 对话界面内的 /init，而不是假定存在同名 shell 子命令。它会检查仓库并创建或更新 AGENTS.md，记录构建命令、目录结构和开发约定。执行后检查修改内容，再决定是否提交到 Git。

opencode.json 配置在哪里？

OpenCode 支持 JSON 和 JSONC。用户级配置通常位于 ~/.config/opencode/opencode.json，项目级配置位于项目根目录的 opencode.json。自定义文件可通过 OPENCODE_CONFIG 环境变量指定。多个配置会合并，冲突字段按加载优先级覆盖；完整顺序参见配置官方文档。

opencode.json · 示例需替换模型 ID

{
  "$schema": "https://opencode.ai/config.json",
  "model": "你的提供商ID/你的模型ID",
  "instructions": ["AGENTS.md"]
}

model 是单数配置项；不要把通用 SDK 的伪代码当成可直接使用的 OpenCode 配置。模型名称必须以你实际有权限调用的模型为准。

如何连接自定义模型提供商？

内置提供商可先运行 /connect 添加凭据。OpenAI 兼容的自定义服务可选择 Other，记住自己设置的 provider ID，再配置同名字段：

opencode.json · OpenAI Chat Completions 兼容示例

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ai-mirror": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AI镜像服务",
      "options": {
        "baseURL": "https://api.example.com/v1",
        "apiKey": "{env:AI_API_KEY}"
      },
      "models": { "your-model-id": { "name": "你的模型" } }
    }
  },
  "model": "ai-mirror/your-model-id"
}

上面的地址与模型都是占位符，请按服务商文档替换，并在启动 OpenCode 的环境中设置 AI_API_KEY。已通过 /connect 保存凭据时，可省略 options.apiKey。使用 Responses 协议的模型可能需要 @ai-sdk/openai，不能直接套用 Chat Completions 示例。完成后运行 /models 检查模型列表。

需要第三方中转服务时，可查看AI镜像服务；这是独立服务，不代表 OpenCode 官方。实际协议、费用及模型可用性由服务商决定。

让 OpenCode 回答中文

临时对话中直接说明“请使用简体中文回答”。若希望整个项目长期生效，可在项目根目录的 AGENTS.md 中加入：

AGENTS.md

默认使用简体中文解释思路、回答问题和汇报结果。
保留代码标识符、命令和日志的原始语言。

语言规则是上下文指令，不是模型能力保证；遇到冲突时检查项目和用户级规则。更多内容参见官方 Rules 文档。

常用 CLI 与 TUI 命令

位置	命令	用途
终端	`opencode`	启动交互界面
终端	`opencode --version`	确认安装版本
终端	`opencode auth list`	查看认证提供商
TUI	`/connect`	添加凭据
TUI	`/models`	选择可用模型
TUI	`/init`	生成或更新项目规则

网络、认证与错误排查

先检查地址、密钥、权限和模型 ID，再检查代理或证书环境。不要把真实 API Key 贴到公开 Issue 或截图里。对 401、403、429 和连接超时，查看OpenCode 故障排查指南。

桌面客户端与 IDE

图形化客户端、终端和 IDE 的安装路径不同，具体平台支持与发布状态以官方下载页面为准。IDE 集成请参考官方 IDE 文档，不要把某个编辑器的扩展流程套用到所有编辑器。

Zen、Go 与模型订阅

Zen、Go 的定价、免费额度和模型列表可能调整，请分别核对Zen 页面与Go 页面。客户端能安装不代表所有模型调用免费，也不保证第三方订阅可直接转换为 API 凭据。

团队与企业使用

先评估代码发送范围、模型服务隐私政策、密钥管理和工具权限。团队功能与服务方案以官方企业信息为准，本站不承诺未验证的 SSO、审计或私有部署能力。

GitHub 集成

查看官方 GitHub 文档，按仓库权限和工作流配置进行集成。避免将 API 密钥提交到源码。

GitLab 集成

CI 权限、凭据和部署环境应按团队策略设置，具体步骤查看官方 GitLab 文档。