OpenCode 安装与认证 — npm / Homebrew 安装、opencode auth、Provider 配置全指南

简介

OpenCode 是一款面向开发者的开源 AI 编程终端工具，它允许你在命令行环境中直接与 AI 模型交互，实现代码生成、重构、调试等任务。与 Claude Code、Codex CLI 等竞品相比，OpenCode 最大的优势在于其 Provider 中立性——你可以自由选择 OpenAI、Anthropic、Google、本地 Ollama 等数十种后端，而不是被锁定在单一服务商。

然而，灵活性的代价是初始配置稍显复杂。本文将从零开始，带你完成 OpenCode 的安装、认证和 Provider 配置全流程。无论你是 macOS、Linux 还是 Windows 用户，无论你是想快速体验还是深入定制，都能在这里找到对应的操作步骤。

正确的安装和认证不仅是使用 OpenCode 的第一步，更决定了后续所有功能能否正常运行。一个配置错误的 Provider 会导致每次请求都失败，一个缺失的 API Key 会让你的 AI 编程之旅寸步难行。因此，花 15 分钟仔细阅读本篇，将为后续的高效使用打下坚实基础。

安装方式对比与选型
方式一：npm 全局安装
方式二：Homebrew 安装（macOS / Linux）
方式三：二进制直装（Linux / Windows）
验证安装与版本管理
认证机制与 opencode auth 命令
Provider 配置详解
环境变量 vs 配置文件
常见安装与认证问题排查
总结与下篇预告

安装方式对比与选型

OpenCode 提供多种安装途径，每种方式各有适用场景：

安装方式	适用平台	自动更新	依赖要求	推荐场景
npm	全平台	`npm update -g`	Node.js >= 18	已有 Node 环境的开发者
Homebrew	macOS / Linux	`brew upgrade`	Homebrew	macOS 用户首选
二进制直装	Linux / Windows	手动下载	无	CI/CD、无包管理器的环境

前置要求

无论选择哪种安装方式，请确保你的系统满足以下条件：

操作系统：macOS 12+、Ubuntu 20.04+、Debian 11+、Windows 10/11（WSL2 推荐）
终端环境：支持 UTF-8 的现代终端（iTerm2、Windows Terminal、GNOME Terminal 等）
网络：能够访问所选 Provider 的 API 端点（国内用户可能需要代理）
权限：全局安装需要管理员权限（sudo 或管理员终端）

方式一：npm 全局安装

这是最通用的安装方式，适合已经安装了 Node.js 的开发者。

1. 检查 Node.js 版本

OpenCode 需要 Node.js 18 或更高版本。请先确认你的版本：

bash

node --version
# 期望输出: v18.x.x 或更高

如果版本过低，可以通过以下方式升级：

bash

# 使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc
nvm install 20
nvm use 20

# 或使用官方安装包
# 访问 https://nodejs.org 下载 LTS 版本

2. 安装 OpenCode

bash

npm install -g opencode-ai

安装过程中你会看到类似输出：

bash

added 1 package in 3s

如果你的 npm 全局目录没有写入权限，可以使用以下方式之一：

bash

# 方式 A：使用 sudo（Linux）
sudo npm install -g opencode-ai

# 方式 B：修改 npm 全局目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g opencode-ai

3. 验证安装

bash

opencode --version
# 期望输出: opencode/x.y.z

方式二：Homebrew 安装（macOS / Linux）

Homebrew 是 macOS 上最受欢迎的包管理器，也支持 Linux（Linuxbrew）。

1. 安装 Homebrew（如未安装）

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

macOS 用户安装后需要执行：

bash

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2. 安装 OpenCode

bash

brew install opencode

Homebrew 会自动处理所有依赖，安装过程通常只需几秒钟。

3. 验证安装

bash

opencode --version
brew info opencode

4. 更新 OpenCode

当有新版本发布时，可以通过 Homebrew 轻松更新：

bash

brew update
brew upgrade opencode

方式三：二进制直装（Linux / Windows）

对于没有包管理器的环境，可以直接下载预编译的二进制文件。

Linux

bash

# 下载最新版本（以 amd64 为例）
curl -fsSL https://github.com/opencode-ai/opencode/releases/latest/download/opencode-linux-amd64 -o /usr/local/bin/opencode
chmod +x /usr/local/bin/opencode

# 验证
opencode --version

Windows（PowerShell）

powershell

# 下载并添加到 PATH
$version = "latest"
Invoke-WebRequest -Uri "https://github.com/opencode-ai/opencode/releases/$version/download/opencode-windows-amd64.exe" -OutFile "$env:USERPROFILE\.local\bin\opencode.exe"

# 确保目录在 PATH 中
$env:PATH += ";$env:USERPROFILE\.local\bin"

验证安装与版本管理

安装完成后，建议运行以下命令进行全面验证：

bash

# 1. 版本检查
opencode --version

# 2. 帮助信息
opencode --help

# 3. 子命令列表
opencode help

# 4. 检查更新
opencode update  # 如果支持自动更新

版本管理策略

对于团队项目，建议锁定 OpenCode 版本以确保行为一致：

bash

# 在项目根目录创建 .opencode-version
echo "1.2.3" > .opencode-version

# 在 CI/CD 中使用固定版本
npm install -g opencode-ai@1.2.3

认证机制与 opencode auth 命令

OpenCode 支持多种认证方式，核心思路是：通过 API Key 或 OAuth 向 Provider 证明你的身份。不同的 Provider 有不同的认证机制，但 OpenCode 通过统一的接口将它们抽象化了。

基本认证命令

bash

# 查看当前认证状态
opencode auth status

# 交互式配置认证
opencode auth login

# 列出所有已配置的 Provider
opencode auth list

# 删除某个 Provider 的认证
opencode auth remove <provider-name>

方式一：交互式认证（推荐新手）

运行 opencode auth login 后，会进入交互式配置向导：

bash

$ opencode auth login

? Select a provider:
  ❯ OpenAI
    Anthropic
    Google (Gemini)
    Ollama (Local)
    Groq
    Mistral
    ... (更多选项)

? Enter your API key: ************************
✓ Authentication successful for OpenAI
✓ Configuration saved to ~/.config/opencode/config.json

方式二：环境变量认证（推荐 CI/CD）

对于自动化场景，通过环境变量配置认证更为合适：

bash

# OpenAI
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export OPENAI_ORG_ID="org-xxxxxxxxxxxxxxxxxxxxxxxx"  # 可选

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxx"

# Google Gemini
export GOOGLE_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxx"

# Groq
export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxxxxxxxxx"

# 然后直接运行 opencode，它会自动检测环境变量
opencode

方式三：配置文件认证

OpenCode 支持通过配置文件管理多个 Provider 的认证信息。配置文件默认位于 ~/.config/opencode/config.json（macOS/Linux）或 %APPDATA%\opencode\config.json（Windows）。

json

{
  "providers": {
    "openai": {
      "apiKey": "sk-proj-xxxxxxxxxxxxxxxx",
      "organization": "org-xxxxxxxxxxxxxxx",
      "baseUrl": "https://api.openai.com/v1"
    },
    "anthropic": {
      "apiKey": "sk-ant-api03-xxxxxxxxxxxxxxxx",
      "baseUrl": "https://api.anthropic.com"
    },
    "google": {
      "apiKey": "AIzaSyxxxxxxxxxxxxxxxx"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  },
  "defaultProvider": "openai",
  "defaultModel": "gpt-4o"
}

API Key 获取指南

不同 Provider 的 API Key 获取方式：

Provider	获取地址	免费额度	备注
OpenAI	platform.openai.com/api-keys	$5（新用户）	需绑定支付方式
Anthropic	console.anthropic.com	有限免费额度	部分区域受限
Google Gemini	aistudio.google.com	免费（有速率限制）	无需信用卡
Groq	console.groq.com	免费（有速率限制）	推理速度极快
Mistral	console.mistral.ai	€2 免费额度	欧洲服务商
Ollama	本地运行	完全免费	需本地 GPU/CPU
DeepSeek	platform.deepseek.com	新用户赠送	性价比高

Provider 配置详解

Provider 是 OpenCode 与 AI 模型之间的桥梁。配置 Provider 的本质是告诉 OpenCode：「我想用哪个服务商、哪个模型、通过什么方式连接」。

配置文件结构

OpenCode 的配置文件采用 JSON 格式，支持嵌套结构：

json

{
  "providers": {
    "provider-name": {
      "apiKey": "your-key",
      "baseUrl": "https://api.example.com/v1",
      "model": "model-id",
      "options": {
        "temperature": 0.7,
        "maxTokens": 4096,
        "timeout": 30000
      }
    }
  }
}

常见 Provider 配置示例

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "baseUrl": "https://api.openai.com/v1",
      "model": "gpt-4o",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}

Anthropic (Claude)

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "baseUrl": "https://api.anthropic.com",
      "model": "claude-sonnet-4-20250514",
      "options": {
        "temperature": 0.2,
        "maxTokens": 8192
      }
    }
  }
}

Ollama（本地模型）

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "qwen2.5-coder:32b",
      "options": {
        "temperature": 0.3,
        "numCtx": 8192
      }
    }
  }
}

注意：Ollama 不需要 API Key，因为它是本地运行的。

兼容 OpenAI 接口的第三方服务

许多服务（如 Azure OpenAI、LocalAI、vLLM）提供了兼容 OpenAI 的 API 接口，可以直接复用 OpenAI 的配置格式：

json

{
  "providers": {
    "azure-openai": {
      "apiKey": "${AZURE_API_KEY}",
      "baseUrl": "https://your-resource.openai.azure.com/openai/deployments/gpt-4o",
      "model": "gpt-4o",
      "options": {
        "apiVersion": "2024-06-01"
      }
    }
  }
}

使用环境变量引用

配置文件中支持使用 ${ENV_VAR} 语法引用环境变量，这样可以将敏感信息排除在配置文件之外：

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

然后在你的 shell 配置文件中设置：

bash

# ~/.bashrc 或 ~/.zshrc
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"

环境变量 vs 配置文件

两种方式各有优劣：

维度	环境变量	配置文件
安全性	高（不落地）	中（文件需设权限）
多 Provider	需要多个变量	统一管理
CI/CD 友好	✓ 天然支持	需要生成文件
版本控制	不适合	可提交模板
切换 Provider	修改变量	修改配置

最佳实践：敏感信息（API Key）用环境变量，非敏感配置（baseUrl、model、options）用配置文件。

常见安装与认证问题排查

问题 1：`command not found: opencode`

原因：npm 全局目录不在 PATH 中。

解决方案：

bash

# 查找 opencode 安装位置
npm list -g opencode-ai

# 将 bin 目录加入 PATH
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

问题 2：`Authentication failed`

原因：API Key 无效或过期。

解决方案：

bash

# 检查环境变量是否正确
echo $OPENAI_API_KEY

# 重新登录
opencode auth login

# 验证 Key 是否有效
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models | head -20

问题 3：Node.js 版本过低

原因：系统自带的 Node.js 版本太旧。

解决方案：使用 nvm 管理 Node.js 版本（见前文安装部分）。

问题 4：网络超时 / 连接被拒

原因：无法访问 Provider 的 API 端点。

解决方案：

bash

# 测试连通性
curl -I https://api.openai.com/v1

# 配置代理（如需要）
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

# 或在配置文件中设置代理
{
  "httpProxy": "http://127.0.0.1:7890"
}

问题 5：权限拒绝（Permission denied）

原因：配置文件权限不正确。

解决方案：

bash

# 检查配置文件权限
ls -la ~/.config/opencode/config.json

# 设置正确的权限（仅所有者可读写）
chmod 600 ~/.config/opencode/config.json

总结与下篇预告

本篇我们完成了 OpenCode 从安装到认证的全流程配置。核心要点回顾：

三种安装方式：npm 适合已有 Node.js 的开发者，Homebrew 是 macOS 用户的首选，二进制直装适合 CI/CD 和无包管理器的环境。
认证机制：支持交互式登录、环境变量和配置文件三种方式。推荐使用环境变量存储 API Key，配置文件管理其他参数。
Provider 配置：OpenCode 的核心优势在于 Provider 中立性，可以轻松切换 OpenAI、Anthropic、Google、Ollama 等后端。
安全最佳实践：永远不要将 API Key 硬编码到代码中，使用环境变量或加密存储；配置文件权限设为 600。

安装和认证只是开始，接下来我们将深入探讨 OpenCode 最核心的功能之一：Provider 与模型选择。不同的 Provider 提供不同的模型，每个模型在能力、速度、价格上各有千秋。如何为你的具体任务选择最合适的模型？--model 参数如何使用？各种 Provider 的详细配置参数是什么？