Sooua
登录
返回文章列表
OpenCode··8 分钟阅读

安装与环境准备

使用官方安装脚本，一行命令搞定：

#OpenCode#AI 编程#终端 Agent

目标：在所有主流平台上安装 OpenCode

前提条件

  1. 现代终端模拟器（TUI 模式需要）

  2. API 密钥 — 任意 LLM 提供商（后续配置）

快速安装（推荐）

使用官方安装脚本，一行命令搞定：

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

安装完成后，验证：

opencode --version

各平台安装流程图

整体安装流程

macOS / Linux 详细安装流程

各平台详细安装

macOS / Linux

方式一：Homebrew（推荐 macOS）

# 推荐：使用 OpenCode 官方 tap（版本最新）
brew install anomalyco/tap/opencode
 
# 或：Homebrew 官方（更新较慢）
brew install opencode

验证安装：

which opencode
opencode --version

方式二：Node.js（跨平台通用）

# npm
npm install -g opencode-ai
 
# Bun（更快）
bun install -g opencode-ai
 
# pnpm
pnpm install -g opencode-ai
 
# Yarn
yarn global add opencode-ai

验证 npm 全局安装路径：

npm list -g opencode-ai
# 如不在 PATH，添加：
export PATH="$PATH:$(npm config get prefix)/bin"

方式三：Arch Linux

# 稳定版
sudo pacman -S opencode
 
# 最新版（AUR）
paru -S opencode-bin
# 或
yay -S opencode-bin

方式四：Mise（版本管理）

mise use -g github:anomalyco/opencode

方式五：Docker

# 交互式运行
docker run -it --rm ghcr.io/anomalyco/opencode
 
# 挂载本地项目
docker run -it --rm -v $(pwd):/workspace -w /workspace ghcr.io/anomalyco/opencode

Windows

强烈推荐使用 WSL（Windows Subsystem for Linux），OpenCode 在 WSL 下体验最佳，功能最完整。

WSL 安装步骤

  1. 安装 WSL2（PowerShell 管理员）：

    wsl --install

  2. 在 WSL 中安装 OpenCode：

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

  3. 在 WSL 中运行：

    opencode

Windows 原生安装

如果确实需要在 Windows 原生环境运行：

# Chocolatey
choco install opencode
 
# Scoop
scoop install opencode
 
# NPM
npm install -g opencode-ai
 
# Mise
mise use -g github:anomalyco/opencode

⚠️ 注意：Windows 原生环境部分功能可能受限，Bun 安装方式正在开发中。

二进制文件

也可以直接从 GitHub Releases 下载对应平台的二进制文件：

# Linux x64
curl -L -o opencode https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-x64
chmod +x opencode
sudo mv opencode /usr/local/bin/

Docker Compose 示例

对于团队开发或 CI/CD 环境，使用 Docker Compose：

# docker-compose.yml
version: '3.8'
 
services:
  opencode:
    image: ghcr.io/anomalyco/opencode:latest
    container_name: opencode-dev
    volumes:
      - ./:/workspace
      - ~/.config/opencode:/root/.config/opencode
      - ~/.local/share/opencode:/root/.local/share/opencode
    working_dir: /workspace
    environment:
      - OPENCODE_CONFIG=/root/.config/opencode/opencode.json
    stdin_open: true
    tty: true
    command: opencode

使用：

# 启动
docker-compose run --rm opencode
 
# 或直接
docker compose run --rm opencode

团队共享配置的进阶版本：

# docker-compose.team.yml
version: '3.8'
 
services:
  opencode:
    image: ghcr.io/anomalyco/opencode:latest
    volumes:
      - ./:/workspace
      - ./.opencode:/root/.config/opencode:ro  # 项目级配置
      - opencode-cache:/root/.cache/opencode
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    working_dir: /workspace
    stdin_open: true
    tty: true
 
volumes:
  opencode-cache:

验证脚本

创建一个完整的安装验证脚本：

#!/bin/bash
# verify-opencode.sh - OpenCode 安装验证脚本
 
set -e
 
echo "🔍 检查 OpenCode 安装..."
 
# 1. 检查命令是否存在
if ! command -v opencode &> /dev/null; then
    echo "❌ opencode 命令未找到"
    echo "   请检查 PATH 或重新安装"
    exit 1
fi
echo "✅ opencode 命令可用"
 
# 2. 检查版本
VERSION=$(opencode --version)
echo "✅ 版本: $VERSION"
 
# 3. 检查终端支持
echo ""
echo "🔍 检查终端兼容性..."
if [ -n "$TERM" ]; then
    echo "✅ TERM=$TERM"
else
    echo "⚠️ TERM 未设置，可能影响显示"
fi
 
# 4. 检查色彩支持
if [ -t 1 ]; then
    COLORS=$(tput colors 2>/dev/null || echo 0)
    if [ "$COLORS" -ge 256 ]; then
        echo "✅ 支持 $COLORS 色"
    else
        echo "⚠️ 仅支持 $COLORS 色，建议使用真彩色终端"
    fi
else
    echo "⚠️ 非交互式终端"
fi
 
# 5. 检查配置文件目录
CONFIG_DIR="$HOME/.config/opencode"
if [ -d "$CONFIG_DIR" ]; then
    echo "✅ 配置目录存在: $CONFIG_DIR"
else
    echo "ℹ️ 配置目录未创建，首次运行会自动生成: $CONFIG_DIR"
fi
 
# 6. 检查 API 密钥配置
AUTH_FILE="$HOME/.local/share/opencode/auth.json"
if [ -f "$AUTH_FILE" ]; then
    echo "✅ 认证文件存在"
else
    echo "⚠️ 未配置 API 密钥，运行 opencode 后使用 /connect 配置"
fi
 
echo ""
echo "🎉 验证完成！运行 'opencode' 开始使用"

运行验证：

chmod +x verify-opencode.sh
./verify-opencode.sh

安装后检查

# 检查版本
opencode --version
 
# 查看帮助
opencode --help
 
# 检查 TUI 是否正常工作
opencode

如果看到 OpenCode 的 TUI 界面，说明安装成功！

常见问题排查

Q: 安装后找不到 opencode 命令

# 检查 PATH
echo $PATH
 
# 如果是手动安装，可能需要添加到 PATH
export PATH="$HOME/.local/bin:$PATH"
 
# 查看具体安装位置
which opencode || find ~ -name opencode -type f 2>/dev/null
 
# npm 全局安装的特殊处理
export PATH="$PATH:$(npm config get prefix)/bin"

Q: Windows 下终端显示异常

  • 使用 Windows Terminal 或上述推荐的终端
  • 确保使用支持 Unicode 和真彩色的字体（如 JetBrains Mono、Cascadia Code）
  • 推荐在 WSL 中使用
  • 检查终端编码：echo $LANG，应为 en_US.UTF-8 或类似

Q: Docker 安装如何挂载本地项目

# 基本挂载
docker run -it --rm -v $(pwd):/workspace -w /workspace ghcr.io/anomalyco/opencode
 
# 同时挂载配置
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.config/opencode:/root/.config/opencode \
  -w /workspace \
  ghcr.io/anomalyco/opencode

Q: 安装脚本执行失败

# 检查 curl 是否可用
curl --version
 
# 使用 wget 替代
wget -qO- https://opencode.ai/install | bash
 
# 或手动下载后执行
curl -fsSL https://opencode.ai/install -o install.sh
bash install.sh

Q: WSL 中无法访问 Windows 文件

# WSL 中 Windows 磁盘挂载在 /mnt
# 例如访问 D 盘项目
cd /mnt/d/my-project
opencode
 
# 或在 Windows 终端中直接运行 wsl opencode

Q: 权限被拒绝（Permission Denied）

# 检查文件权限
ls -la $(which opencode)
 
# 修复权限
chmod +x $(which opencode)
 
# 或重新安装到用户目录
curl -fsSL https://opencode.ai/install | bash

避坑清单

⚠️ 坑点说明解决方案
使用默认 Windows CMD不支持 TUI 的 Unicode 和真彩色安装 Windows Terminal + WSL2
npm 全局包不在 PATH安装成功但找不到命令添加 $(npm config get prefix)/bin 到 PATH
Docker 未挂载卷容器内修改无法保存始终使用 -v $(pwd):/workspace
旧版终端模拟器界面乱码或错位升级到 WezTerm / Alacritty / Ghostty
WSL1 而非 WSL2性能差、兼容性差wsl --set-version <distro> 2
防火墙阻止安装脚本curl 下载失败使用代理或手动下载二进制

真实场景案例

案例 1：团队统一开发环境

场景：团队有 5 名开发者，使用不同操作系统（macOS、Ubuntu、Windows），需要统一 OpenCode 版本和配置。

解决方案：

# docker-compose.yml
docker run -it --rm \
  -v $(pwd):/workspace \
  -v $(pwd)/.opencode-team:/root/.config/opencode:ro \
  ghcr.io/anomalyco/opencode:v1.2.3  # 锁定版本

团队共享 /.opencode-team/opencode.json：

{
  "model": "anthropic/claude-sonnet-4",
  "formatters": {
    "*.ts": "prettier --write"
  }
}

案例 2：CI/CD 集成

场景：在 GitHub Actions 中使用 OpenCode 进行自动化代码审查。

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run OpenCode Review
        run: |
          docker run --rm \
            -v ${{ github.workspace }}:/workspace \
            -e ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
            ghcr.io/anomalyco/opencode \
            opencode --no-tui "请审查这个 PR 的代码变更，关注安全性和性能"

案例 3：无网络环境离线安装

场景：内网开发环境无法访问公网，需要离线安装。

# 在有网络的机器上下载
curl -L -o opencode-linux-x64 https://github.com/anomalyco/opencode/releases/latest/download/opencode-linux-x64
 
# 传输到内网
scp opencode-linux-x64 user@internal-server:/tmp/
 
# 在内网安装
ssh user@internal-server
chmod +x /tmp/opencode-linux-x64
sudo mv /tmp/opencode-linux-x64 /usr/local/bin/opencode

下一步

安装完成后，配置 API 密钥，开始第一次使用：

下一篇：03. 第一次运行

分享

评论

请 登录 后参与讨论。

加载中…

相关文章

OpenCode··6 分钟

故障排查指南

flowchart TD

#OpenCode#AI 编程#终端 Agent
OpenCode··3 分钟

企业部署与治理

flowchart TB

#OpenCode#AI 编程#终端 Agent
OpenCode··5 分钟

IDE 扩展开发

flowchart TB

#OpenCode#AI 编程#终端 Agent