OpenCode 中文社区

Appearance

安装常见问题 ​

安装问题解决指南

本页面汇总了 OpenCode 安装过程中常见的问题及解决方案。如果你遇到安装问题，请先查阅本指南。

🚀 安装前准备 ​

1. 系统要求 ​

操作系统最低版本推荐版本注意事项
Windows1011需要管理员权限
macOS10.15 (Catalina)13+ (Ventura)需要 Homebrew
LinuxUbuntu 18.04Ubuntu 22.04需要 sudo 权限

其他要求：

  • Node.js 16+（推荐 18+）
  • npm 7+ 或 pnpm/yarn
  • Git 2.20+
  • 至少 2GB 可用磁盘空间

❌ 安装失败问题 ​

1. 权限问题 ​

错误信息 ​

bash
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

解决方案 ​

macOS/Linux：

bash
# 方法 1：使用 sudo（不推荐）
sudo npm install -g @opencode/cli

# 方法 2：修改 npm 目录权限（推荐）
sudo chown -R $(whoami) /usr/local/lib/node_modules
npm install -g @opencode/cli

# 方法 3：使用 nvm（最佳实践）
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
# 安装 Node.js
nvm install --lts
# 安装 OpenCode
npm install -g @opencode/cli

Windows：

  1. 以管理员身份运行命令提示符（右键 → 以管理员身份运行）。
  2. 重新运行安装命令：
    bash
    npm install -g @opencode/cli

2. 网络问题 ​

错误信息 ​

bash
npm ERR! network timeout at: https://registry.npmjs.org/@opencode/cli
npm ERR! network This is a problem related to network connectivity.

解决方案 ​

方法 1：切换 npm 镜像源

bash
# 使用淘宝镜像（国内用户）
npm config set registry https://registry.npmmirror.com

# 使用官方源（国外用户）
npm config set registry https://registry.npmjs.org

方法 2：配置代理

bash
# HTTP 代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# SOCKS5 代理
npm config set proxy socks5://127.0.0.1:1080
npm config set https-proxy socks5://127.0.0.1:1080

# 取消代理
npm config delete proxy
npm config delete https-proxy

方法 3：使用 VPN

  • 确保 VPN 已连接。
  • 重试安装命令。

方法 4：离线安装

  1. 下载离线安装包：OpenCode 离线安装包
  2. 本地安装：
    bash
    npm install -g ./opencode-cli.tgz

3. Node.js 版本问题 ​

错误信息 ​

bash
Error: OpenCode requires Node.js 16 or higher. You are using Node.js 14.17.0

解决方案 ​

方法 1：升级 Node.js

bash
# 使用 nvm（推荐）
nvm install 18
nvm use 18

# 直接下载安装
# 下载地址：https://nodejs.org/

方法 2：使用多版本管理

bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# 安装多个 Node.js 版本
nvm install 16
nvm install 18

# 切换版本
nvm use 18

验证 Node.js 版本：

bash
node --version  # 应显示 v16.x 或更高
npm --version   # 应显示 7.x 或更高

4. 依赖冲突 ​

错误信息 ​

bash
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Found: typescript@4.9.5
npm ERR! node_modules/typescript
npm ERR!   typescript@"^4.0.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer typescript@">=5.0.0" from @opencode/cli@2.1.0

解决方案 ​

方法 1：更新依赖

bash
npm install -g typescript@latest

方法 2：使用 --legacy-peer-deps

bash
npm install -g @opencode/cli --legacy-peer-deps

方法 3：使用 pnpm 或 yarn

bash
# 使用 pnpm
pnpm add -g @opencode/cli

# 使用 yarn
yarn global add @opencode/cli

5. 安装超时 ​

错误信息 ​

bash
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@opencode/cli failed, reason: connect ETIMEDOUT 104.16.25.35:443

解决方案 ​

方法 1：增加超时时间

bash
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000

方法 2：使用镜像源

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

方法 3：清理缓存

bash
npm cache clean --force

✅ 安装后问题 ​

1. 命令不存在 ​

错误信息 ​

bash
command not found: opencode

解决方案 ​

macOS/Linux：

bash
# 检查 npm 全局安装路径
npm config get prefix

# 将 npm 全局路径添加到 PATH
# 编辑 ~/.zshrc 或 ~/.bashrc
export PATH="$(npm config get prefix)/bin:$PATH"

# 使更改生效
source ~/.zshrc  # 或 source ~/.bashrc

Windows：

  1. 检查 npm 全局安装路径：
    bash
    npm config get prefix
  2. 将路径添加到系统环境变量 PATH。
  3. 重启命令提示符。

2. 版本验证失败 ​

错误信息 ​

bash
opencode --version
# 输出：OpenCode CLI version unknown

解决方案 ​

方法 1：重新安装

bash
npm uninstall -g @opencode/cli
npm install -g @opencode/cli

方法 2：检查安装路径

bash
# 查找 opencode 命令路径
which opencode  # macOS/Linux
where opencode  # Windows

# 确保路径正确
ls -l $(which opencode)  # 检查是否为符号链接

3. 模块加载失败 ​

错误信息 ​

bash
Error: Cannot find module '@opencode/core'

解决方案 ​

方法 1：重新安装依赖

bash
npm rebuild

方法 2：清理缓存并重装

bash
npm cache clean --force
rm -rf node_modules
npm install

方法 3：检查全局安装

bash
# 查看全局安装的模块
npm list -g --depth=0

# 重新安装
npm install -g @opencode/cli@latest

🌐 网络配置问题 ​

1. 国内网络访问 ​

问题描述 ​

国内用户访问 OpenAI/Anthropic 等国外 API 时，可能遇到网络连接问题。

解决方案 ​

方法 1：配置代理

bash
opencode config set proxy http://127.0.0.1:7890

方法 2：使用国内模型

bash
# 配置智谱 AI
opencode config set provider zhipu
opencode config set zhipu.api_key "your-api-key"
opencode config set zhipu.model "glm-4"

# 配置 DeepSeek
opencode config set provider deepseek
opencode config set deepseek.api_key "your-api-key"

方法 3：使用镜像 API

bash
opencode config set openai.base_url "https://api.openai-proxy.com/v1"

2. 企业网络限制 ​

问题描述 ​

企业网络可能屏蔽了 OpenCode 所需的端口或域名。

解决方案 ​

方法 1：配置代理

bash
opencode config set proxy http://proxy.company.com:8080

方法 2：请求网络白名单 联系 IT 部门，将以下域名和端口加入白名单：

  • api.openai.com（443）
  • api.anthropic.com（443）
  • open.bigmodel.cn（443）
  • api.deepseek.com（443）

方法 3：使用本地模型

bash
# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 配置 OpenCode 使用 Ollama
opencode config set provider ollama
opencode config set ollama.base_url "http://localhost:11434"
opencode config set ollama.model "llama2"

🛠️ 故障排除工具 ​

1. 健康检查 ​

bash
# 运行健康检查
opencode doctor

# 生成诊断报告
opencode doctor --report --output diagnosis-report.html

2. 日志分析 ​

bash
# 查看日志
opencode logs --tail 100

# 导出日志
opencode logs --export --output opencode-logs.txt

3. 网络诊断 ​

bash
# 测试 API 连接
opencode network test --provider openai

# 测试所有提供商
opencode network test --all

4. 缓存清理 ​

bash
# 清理缓存
opencode cache clean

# 重置配置
opencode config reset --soft

🎯 常见问题解答 ​

1. 如何卸载 OpenCode？ ​

bash
# 卸载 CLI
npm uninstall -g @opencode/cli

# 清理配置文件
rm -rf ~/.opencode  # macOS/Linux
rd /s /q "%APPDATA%\OpenCode"  # Windows

2. 如何更新 OpenCode？ ​

bash
# 更新到最新版本
npm update -g @opencode/cli

# 安装特定版本
npm install -g @opencode/cli@2.1.0

3. 如何迁移配置？ ​

bash
# 导出配置
opencode config export --output opencode-config.json

# 导入配置
opencode config import --file opencode-config.json

4. 如何重置 OpenCode？ ​

bash
# 软重置（保留 API 密钥）
opencode config reset --soft

# 硬重置（清除所有配置）
opencode config reset --hard

5. 如何切换 Node.js 版本？ ​

bash
# 使用 nvm 切换版本
nvm install 18
nvm use 18

🚀 下一步 ​

  1. 使用常见问题
  2. 安装指南
  3. 配置指南
  4. 加入社区讨论
微信群