OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

OpenCode 安装教程（官方方式全解析）

OpenCode 是一个 开源的 AI Coding Agent，支持 命令行（CLI）和桌面端（Desktop App） 两种使用方式。

官方提供了多种安装方式，覆盖不同系统与用户习惯。你可以根据自己的情况选择最合适的一种。

安装方式总览（官方支持）

安装方式适合人群是否需要 Node.js
Desktop App普通用户 / 非开发者❌
curl 一行命令macOS / Linux 用户❌
Homebrew / paru熟悉系统包管理器的用户❌
npm / bun前端 / Node.js 开发者✅

方式一：安装 Desktop App（最推荐）

如果你不关心环境配置，直接使用桌面端是最省事的方式。

OpenCode 官方提供 Desktop App，支持：

  • macOS
  • Windows
  • Linux

下载安装后即可使用，无需 Node.js、无需命令行。

👉 官方下载地址：https://opencode.ai

方式二：使用 curl 安装（macOS / Linux）

这是官方推荐的 CLI 安装方式之一，不依赖 Node.js。

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

安装完成后，重新打开终端，验证是否成功：

opencode --version

方式三：使用系统包管理器安装

macOS（Homebrew）

brew install opencode

Arch Linux（paru）

paru -S opencode

方式四：通过 npm / bun 安装（开发者）

如果你已经有 Node.js 环境，也可以通过 npm 或 bun 安装 CLI。

环境要求

  • Node.js v18.0.0 或更高
  • Git

检查 Node.js 版本：

node -v

安装命令

npm install -g @opencode-ai/cli
# 或
bun add -g @opencode-ai/cli

如果遇到权限问题（EACCES）：

sudo npm install -g @opencode-ai/cli

初始化配置（国内用户必看）

安装完成后，运行初始化命令：

opencode init

常见选项说明：

  • Provider

    • Ollama：本地模型
    • OpenAI / DeepSeek：在线 API

  • Language

    • 选择 Chinese，可让 Agent 优先使用中文

设置 API Key（如使用在线模型）

将以下内容写入 ~/.zshrc 或 ~/.bashrc：

export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="sk-xxxxxxxx"

保存后执行：

source ~/.zshrc

验证安装是否成功

opencode run "创建一个 demo.txt 文件，并写入：你好 OpenCode"

常见问题（FAQ）

command not found: opencode

通常是全局安装路径未加入 PATH。

npm config get prefix

确保该路径下的 bin 目录在 PATH 中。

国内网络慢 / 依赖下载失败

npm config set registry https://registry.npmmirror.com

下一步