安装指南

本文档介绍如何在不同操作系统上安装和配置 OpenCode CLI。

系统要求

• 现代终端模拟器（推荐）：WezTerm、Alacritty、Ghostty、Kitty
• Node.js：18.0 或更高版本（使用 npm 安装时）
• 操作系统：macOS、Linux 或 Windows 10+

安装方式

一键安装（推荐）

使用官方安装脚本，自动检测系统并安装：

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

使用包管理器

npm / pnpm / yarn

# npm
npm install -g opencode-ai

# pnpm
pnpm add -g opencode-ai

# yarn
yarn global add opencode-ai

Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

Scoop（Windows）

scoop install opencode

Chocolatey（Windows）

choco install opencode

Arch Linux（paru）

paru -S opencode-bin

Nix

nix-env -iA nixpkgs.opencode

桌面应用程序

OpenCode 也提供桌面应用程序，支持 macOS、Windows 和 Linux：

• 下载地址：opencode.ai/download
• GitHub Releases：github.com/anomalyco/opencode/releases

首次配置

连接 LLM 提供商

安装完成后，运行以下命令配置 API 密钥：

opencode
# 在交互界面中输入
/connect

这将引导你前往 opencode.ai/auth 完成认证和配置。

使用环境变量

也可以通过环境变量配置 API 密钥：

macOS / Linux

编辑 ~/.bashrc、~/.zshrc 或 ~/.profile：

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-your-api-key"

# OpenAI
export OPENAI_API_KEY="sk-your-api-key"

# Google Gemini
export GOOGLE_GENERATIVE_AI_API_KEY="your-google-api-key"

# 代理配置（可选）
export HTTPS_PROXY="http://127.0.0.1:7890"

使配置生效：

source ~/.bashrc  # 或 source ~/.zshrc

Windows PowerShell

# 临时设置
$env:ANTHROPIC_API_KEY = "sk-ant-your-api-key"

# 永久设置
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your-api-key", "User")

验证安装

# 查看版本
opencode --version

# 查看帮助
opencode --help

# 启动交互式会话
opencode

# 查看可用模型
opencode models

配置文件位置

OpenCode 支持多级配置文件，按优先级从低到高：

优先级	位置	说明
1	远程配置	组织级默认配置（.well-known/opencode）
2	全局配置	~/.config/opencode/opencode.json
3	自定义配置	OPENCODE_CONFIG 环境变量指定
4	项目配置	项目根目录 opencode.json
5	.opencode 目录	代理、命令、插件配置
6	内联配置	OPENCODE_CONFIG_CONTENT 环境变量

注意：配置会深度合并，高优先级配置覆盖低优先级配置的相同字段。

推荐终端模拟器

为获得最佳体验，建议使用支持现代特性的终端：

终端	平台	特点
WezTerm	跨平台	GPU 加速、高度可配置
Alacritty	跨平台	极致性能、简洁配置
Ghostty	macOS/Linux	原生性能、现代设计
Kitty	跨平台	功能丰富、图像支持
iTerm2	macOS	功能全面、成熟稳定

常见问题

安装失败：权限不足

# macOS/Linux：修改 npm 全局目录
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# 或使用 Homebrew 安装（推荐）
brew install anomalyco/tap/opencode

连接超时

检查网络代理配置：

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

终端显示异常

确保使用推荐的现代终端模拟器，传统终端可能不支持 OpenCode 的 TUI 特性。

更新到最新版本

# 使用安装脚本更新
curl -fsSL https://opencode.ai/install | bash

# 或使用 opencode 内置命令
opencode upgrade

# 或使用包管理器
npm update -g opencode-ai
brew upgrade opencode

下一步

• 基础配置 - 了解配置文件结构
• Provider 配置 - 配置 LLM 提供商
• MCP 服务 - 扩展工具能力