安装与使用指南

OpenCode 安装与首次使用指南

分清 OpenCode 1 和 2，完成安装，用 ChatGPT、Copilot、API key 或本地模型接入；默认权限偏宽，教你先用 Plan 模式并收紧权限，附 Windows WSL 说明，均链接官方文档。

文档核验2026-10-20

核验日期：2026-10-20。本文依据 OpenCode 官方文档整理，本站尚未在新版 OpenCode 上完成安装实测。OpenCode 更新很快，命令以文中链接的官方页面为准。

OpenCode 是开源的终端编程 Agent，最大的特点是不绑定模型厂商：可以接 OpenAI、Anthropic、Gemini、GitHub Copilot，也可以接本地的 Ollama。第一次用它，最容易出问题的是三件事：装了哪个版本、模型从哪来、谁来付费，以及它默认会不会直接改文件、跑命令。本文按这个顺序讲。

如果你还在比较工具，先看 OpenCode 的功能、适用场景与源码审查结果，或 OpenCode 与 Claude Code 怎么选、OpenCode 与 Kilo Code 怎么选。

先确认：你要装的是 OpenCode 1 还是 OpenCode 2

OpenCode 正在从 1.x 过渡到 2：

	OpenCode 1（1.x）	OpenCode 2
状态	GitHub 正式发布版（核验时为 v1.19.3），主文档对应这个版本	官网首页的安装命令装的是它；文档在 `/v2/docs`，内容还比较少
npm 包	`opencode-ai`	`@opencode/cli`
安装脚本	`https://opencode.ai/install`	`https://opencode.ai/v2/install`

官方文档提醒，两个版本的安装方式可能互相冲突，选一个装就好，不要两个都装。本文的命令以文档最完整的 OpenCode 1 为准；如果你装了 2，命令基本相同，但细节请以 OpenCode 2 文档为准。依据：官方文档首页、GitHub Releases。

第一步：安装

macOS / Linux 用官方安装脚本：

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

也可以用 npm 或 Homebrew（官方推荐 OpenCode 自己的 tap，官方 formula 更新较慢）：

npm install -g opencode-ai
brew install anomalyco/tap/opencode

npm 包名是 opencode-ai，不要装名字相近的第三方包。装好后运行 opencode --version 确认。命令来自官方安装说明。

第二步：接入模型

OpenCode 本身免费开源，费用来自你接入的模型。在项目目录运行 opencode，进入界面后输入 /connect，选择提供方，再按提示用浏览器登录或粘贴 API key。凭据保存在 ~/.local/share/opencode/auth.json，不要提交到仓库；用 opencode auth list 查看已经配置了哪些。

常见的几种接法（见官方 Providers 文档）：

你已有的	怎么接	说明
ChatGPT Plus / Pro	`/connect` → OpenAI → ChatGPT Plus/Pro，浏览器登录	使用套餐额度
GitHub Copilot	`/connect` → GitHub Copilot，到 `github.com/login/device` 输入设备码	官方注明部分模型需要 Pro+
各家 API key	`/connect` → 对应厂商 → 粘贴 key	按 API 价格计费
OpenCode 官方模型服务	`/connect` → opencode，到 `opencode.ai/auth` 登录、添加付款方式、复制 key	按次计费；另有若干标注 Free 的模型，官方注明是限时免费，名单经常变
本地模型（Ollama、LM Studio）	在 `opencode.json` 里配置	免费，但对电脑配置有要求

关于 Claude Pro / Max 订阅：官方文档写明，有第三方插件可以让 OpenCode 使用 Claude Pro/Max 订阅，但 Anthropic 明确禁止这种用法，OpenCode 从 1.3.0 起已移除内置的相关插件。想在 OpenCode 里用 Claude 模型，请用 Anthropic API key。

本地 Ollama 的配置示例（来自官方文档，模型名换成你本地有的模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}

官方提示：本地模型调用工具失败时，可以把 Ollama 的 num_ctx 调大到 16k–32k 试试。

第三步：第一个任务与权限（重要）

和 Codex、Claude Code 不同，OpenCode 默认不先问你就会改文件、跑命令。 按官方权限文档，大多数权限默认是 allow；只有访问项目目录以外的路径（external_directory）和疑似死循环（doom_loop）默认会先询问；.env 文件默认禁止读取。

所以第一次上手，建议这样做：

在一个用 Git 管理、已经提交干净的项目里运行 opencode，出了问题可以直接回滚。
按 Tab 切换到 Plan 模式再提问。按官方 Agents 文档，Plan 模式下改文件和执行 bash 命令默认都要先征求你的同意；默认的 Build 模式则拥有全部权限。
想让 Build 模式也先问你，在项目根目录的 opencode.json 里写：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow"
    }
  }
}

规则按顺序匹配、后写的优先，所以通配的 "*" 要放在最前面。每次询问时可以选“仅这一次”“本次会话都允许”或“拒绝”。

第四步：用 AGENTS.md 让它了解你的项目

在项目里运行 /init，OpenCode 会分析代码并在项目根目录生成 AGENTS.md，记录项目结构、构建和测试命令、代码约定。官方建议把它提交到 Git，团队共用。之后可以手动补充“改完先跑测试”“不要动 migrations 目录”这类约定。见官方文档首页。

Windows 用户注意

官方推荐在 WSL 里使用 OpenCode，理由是文件系统性能、终端支持和开发工具兼容性更好。步骤：先按微软官方文档装好 WSL，然后在 WSL 终端里运行第一步的安装脚本。Windows 的 C 盘在 WSL 里是 /mnt/c/；想要更快，就把项目克隆到 WSL 自己的目录（如 ~/code/）里再运行。

如果不想用 WSL，也可以用 choco install opencode、scoop install opencode 或 npm 安装。见官方 Windows (WSL) 说明。

常见问题

OpenCode 免费吗？ 软件本身开源免费（MIT 许可证，源码在 anomalyco/opencode）。要花钱的是模型：用 ChatGPT 或 Copilot 套餐、各家 API key，或 OpenCode 官方的按次计费服务；完全免费的路子是本地模型，或官方限时开放的 Free 模型。

OpenCode 会上传我的代码吗？ 官网说明 OpenCode 本身不存储你的代码和上下文数据；但你的代码会发给你接入的模型提供方，适用对方的数据政策。

能用 Claude 订阅吗？ 不建议。官方文档写明 Anthropic 明确禁止通过插件用 Claude Pro/Max 订阅接入 OpenCode，请改用 Anthropic API key。

在中国大陆能用吗？ OpenCode 软件本身可以安装；能不能用取决于你接入的模型服务在当地是否可用。接入国内可访问的模型服务（填 API key 或兼容 OpenAI 的 baseURL），或使用本地模型，是更稳妥的做法。

和 Claude Code 怎么选？ 主要看你是否需要换模型、是否在意开源。详细对比见 OpenCode vs Claude Code；也可以看 AI 编程 Agent 排行榜。