OpenCode 完整安装指南：从零开始到首次运行的全流程教程

OpenCode 是一款强大的 AI 驱动编程助手，支持代码生成、重构、调试和文档编写。本文将带你从零开始完成 OpenCode 的安装、配置和首次运行，确保你能快速上手并发挥其全部潜力。

什么是 OpenCode？

OpenCode 是一个开源的 AI 编程助手，它将大语言模型的能力与代码编辑器深度集成，让开发者可以通过自然语言完成复杂的编程任务。

核心特性

• 多模型支持: 免费使用 GLM-4.7，也支持 Claude、GPT-4、Gemini 等顶级模型
• 终端原生: 纯命令行界面，轻量高效，无需图形界面
• 插件生态: 支持自定义插件，扩展工具能力（MCP、Skills）
• 代码感知: 自动理解项目结构，提供上下文相关的建议
• 多语言支持: Python、JavaScript、TypeScript、Go、Rust 等主流语言

适用场景

系统要求

在开始安装前，请确保你的系统满足以下要求：

最低配置

• 操作系统: macOS 10.15+, Linux (Ubuntu 20.04+), Windows 10+ (WSL2)
• 内存: 4GB RAM（推荐 8GB+）
• 磁盘空间: 500MB 可用空间
• 网络: 稳定的互联网连接（首次下载模型需要）

软件依赖

根据安装方式不同，可能需要：

• Homebrew 安装: macOS 或 Linux 系统上的 Homebrew
• NPM 安装: Node.js 16+ 或 Bun 运行时
• 脚本安装: Bash shell 和 curl 工具

安装方式选择指南

OpenCode 提供多种安装方式，选择最适合你的：

方式 A：使用 Homebrew 安装（推荐 Mac 用户）

Homebrew 是 macOS 上最流行的包管理器，也支持 Linux。

步骤 1：安装 Homebrew（如果尚未安装）

# 检查是否已安装
brew --version

# 如未安装，运行以下命令（需要 5-10 分钟）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步骤 2：添加 OpenCode Tap

# 添加 OpenCode 官方仓库
brew tap anomalyco/tap

# 更新 Homebrew 索引
brew update

步骤 3：安装 OpenCode

brew install opencode

# 安装完成后，验证版本
opencode --version

预期输出:

OpenCode v1.8.2 (Build 20260122)

步骤 4：首次配置

# 启动 OpenCode
opencode

# 首次运行会自动下载 GLM-4.7 模型（约 2GB）
# 下载完成后会显示欢迎界面

方式 B：使用 NPM 或 Bun 安装

适合已有 Node.js 环境的开发者。

检查 Node.js 版本

node --version  # 需要 v16.0.0 或更高
npm --version

# 或使用 bun（更快）
bun --version

如果未安装 Node.js，从 Node.js 官网 下载安装。

全局安装 OpenCode

# 使用 npm
npm install -g opencode-ai

# 或使用 bun（推荐，速度更快）
bun add -g opencode-ai

验证安装

# 检查命令是否可用
which opencode
# 输出示例：/usr/local/bin/opencode

# 查看版本
opencode --version

解决路径问题（如果命令不可用）

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

# 将路径添加到 PATH（以 ~/.zshrc 为例）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 重新验证
opencode --version

方式 C：使用官方安装脚本

最简单的一键安装方式，适用于 Linux 和 macOS。

运行安装脚本

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

脚本会自动:

1. 检测操作系统和架构
2. 下载对应的二进制文件
3. 安装到 ~/.local/bin/opencode
4. 配置环境变量

手动添加到 PATH（如需要）

# 检查安装位置
ls -la ~/.local/bin/opencode

# 添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # 或 ~/.zshrc
source ~/.bashrc

方式 D：下载图形界面版本

如果你不习惯使用命令行，OpenCode 也提供独立的桌面应用。

下载步骤

1. 访问 https://opencode.ai/download
2. 根据操作系统选择：
   • macOS: OpenCode-macOS-arm64.dmg (Apple Silicon) 或 OpenCode-macOS-x64.dmg (Intel)
   • Windows: OpenCode-Setup.exe
   • Linux: OpenCode-linux-x64.AppImage
3. 下载后按标准流程安装

macOS 安装

# 打开 DMG 文件
open OpenCode-macOS-arm64.dmg

# 将 OpenCode 拖拽到 Applications 文件夹
# 首次打开时，右键点击并选择"打开"绕过安全提示

Windows 安装

1. 双击 OpenCode-Setup.exe
2. 按照安装向导提示操作
3. 安装完成后，从开始菜单启动 OpenCode

验证安装与首次运行

无论使用哪种安装方式，都应该进行以下验证。

基础验证

# 1. 检查版本
opencode --version

# 2. 查看帮助信息
opencode --help

# 3. 检查配置目录
ls -la ~/.config/opencode

首次启动

# 启动 OpenCode
opencode

# 如果是首次运行，会看到欢迎界面：

预期输出:

┌──────────────────────────────────────┐
│  Welcome to OpenCode v1.8.2          │
│  Type /help to see available commands│
└──────────────────────────────────────┘

Using model: glm-4.7 (free, no API key required)

>

测试基础功能

# 在 OpenCode 提示符下输入
> Hello, can you help me write a function to reverse a string?

# 应该得到类似的回复和代码：

预期回复:

function reverseString(str) {
  return str.split('').reverse().join('');
}

// Usage:
console.log(reverseString("hello"));  // "olleh"

验证免费模型

# 检查当前使用的模型
> /models

# 输出应包含 glm-4.7

如果一切正常，恭喜你已成功安装 OpenCode！

配置与个性化

配置文件位置

OpenCode 的配置文件位于：

• macOS/Linux: ~/.config/opencode/opencode.json
• Windows: %APPDATA%\opencode\opencode.json

基础配置示例

{
  "defaultModel": "glm-4.7",
  "theme": "dark",
  "autoSave": true,
  "maxTokens": 2048,
  "temperature": 0.7
}

配置多个模型

如果你有其他 API Key（如 OpenAI、Anthropic），可以添加：

{
  "models": [
    {
      "name": "glm-4.7",
      "provider": "default",
      "free": true
    },
    {
      "name": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "apiKey": "YOUR_ANTHROPIC_KEY"
    }
  ],
  "defaultModel": "glm-4.7"
}

切换模型

# 在 OpenCode 中切换模型
> /model set claude-3-5-sonnet-20241022

# 查看所有可用模型
> /models

实战示例：完整工作流程

让我们通过一个真实示例，演示 OpenCode 的完整使用流程。

场景：创建一个 Node.js HTTP 服务器

# 1. 创建项目目录
mkdir my-server
cd my-server

# 2. 在项目目录启动 OpenCode
opencode

# 3. 开始对话
> Create a simple Node.js HTTP server that:
> 1. Listens on port 3000
> 2. Has a /health endpoint returning JSON status
> 3. Has a /api/users endpoint with mock user data
> 4. Includes error handling
>
> Please write the code and save it to server.js

OpenCode 会:

1. 生成完整的代码
2. 自动创建 server.js 文件
3. 添加必要的错误处理和注释

生成的代码（示例）:

const http = require('http');

const PORT = 3000;

// Mock user data
const users = [
  { id: 1, name: 'Alice', email: '[email protected]' },
  { id: 2, name: 'Bob', email: '[email protected]' }
];

const server = http.createServer((req, res) => {
  // Health check endpoint
  if (req.url === '/health' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'OK', timestamp: new Date().toISOString() }));
    return;
  }

  // Users API endpoint
  if (req.url === '/api/users' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ data: users }));
    return;
  }

  // 404 for other routes
  res.writeHead(404, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ error: 'Not Found' }));
});

server.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}/`);
});

// Error handling
server.on('error', (err) => {
  console.error('Server error:', err);
  process.exit(1);
});

运行和测试

# 4. 退出 OpenCode（按 Ctrl+D 或输入 /exit）
> /exit

# 5. 运行服务器
node server.js

# 6. 在另一个终端测试
curl http://localhost:3000/health
curl http://localhost:3000/api/users

故障排查

问题 1：command not found: opencode

症状: 运行 opencode 时提示命令未找到。

可能原因:

1. 未正确安装
2. 可执行文件不在 PATH 中

解决方案:

# 1. 确认是否安装成功
which opencode

# 2. 如果找不到，检查安装位置
# Homebrew 通常在：/opt/homebrew/bin/opencode
# NPM 通常在：$(npm config get prefix)/bin/opencode

# 3. 手动添加到 PATH
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. 重新验证
opencode --version

问题 2：模型下载失败

症状: 首次启动时卡在"Downloading model…"

可能原因:

• 网络连接不稳定
• 防火墙阻止下载
• 磁盘空间不足

解决方案:

# 1. 检查网络连接
ping -c 3 opencode.ai

# 2. 检查磁盘空间
df -h

# 3. 手动下载模型
opencode --download-model glm-4.7

# 4. 使用国内镜像（如有）
export OPENCODE_MIRROR=https://mirror.opencode.cn
opencode

问题 3：NPM 安装后权限错误

症状: npm install -g opencode-ai 报 EACCES 错误

解决方案:

# 方案 A: 修改 npm 全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 重新安装
npm install -g opencode-ai

# 方案 B: 使用 npx（无需全局安装）
npx opencode-ai

问题 4：macOS 提示"无法验证开发者"

症状: 图形界面版本首次打开时被 macOS 阻止

解决方案:

# 1. 右键点击 OpenCode 应用
# 2. 选择"打开"而不是双击
# 3. 在弹出对话框中点击"打开"

# 或使用命令行：
sudo xattr -r -d com.apple.quarantine /Applications/OpenCode.app

问题 5：Windows 杀毒软件误报

症状: Windows Defender 或其他杀毒软件阻止运行

解决方案:

1. 打开 Windows 安全中心
2. 点击"病毒和威胁防护"
3. 选择"管理设置"
4. 添加 OpenCode 到排除列表

问题 6：启动后无响应

症状: 运行 opencode 后终端无任何输出

调试步骤:

# 1. 以调试模式启动
opencode --debug

# 2. 查看日志
cat ~/.config/opencode/logs/latest.log

# 3. 检查配置文件
cat ~/.config/opencode/opencode.json

# 4. 重置配置
mv ~/.config/opencode ~/.config/opencode.backup
opencode

下一步：深入学习 OpenCode

成功安装后，你可能想了解：

相关教程

• OpenCode MCP 配置指南 - 配置 Model Context Protocol 扩展能力
• OpenCode Skills 安装指南 - 安装专业技能包
• OpenCode 整合 Antigravity - 免费使用顶级大模型

Claude 生态系统

• Claude Code Skills 完整指南 - 了解 Skills 模块化扩展机制
• Claude Agent SDK 教程 - 构建自定义 AI Agent
• Antigravity UI 设计指南 - AI 辅助快速构建页面

官方资源

• OpenCode 官方文档 - 完整 API 参考
• 插件市场 - 探索社区插件
• GitHub 仓库 - 查看源码和贡献

常见问题 (FAQ)

Q1: OpenCode 是免费的吗？

A: 是的，OpenCode 本身是开源且免费的。默认使用 GLM-4.7 免费模型，无需 API Key。如果你想使用 Claude、GPT-4 等高级模型，需要自己的 API 密钥（按模型提供商收费）。

Q2: 与 GitHub Copilot 有什么区别？

A: 主要区别：

Q3: 如何更新 OpenCode？

A: 根据安装方式不同：

# Homebrew
brew upgrade opencode

# NPM
npm update -g opencode-ai

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

# 图形界面：应用内检查更新

Q4: 支持哪些编程语言？

A: OpenCode 支持所有主流编程语言，包括但不限于：

• Web: JavaScript, TypeScript, HTML, CSS, React, Vue
• 后端: Python, Java, Go, Rust, PHP, Ruby
• 移动: Swift, Kotlin, Dart
• 数据: SQL, R, Julia

Q5: 可以在公司项目中使用吗？

A: 可以，但请注意：

• OpenCode 本身是开源软件（查看许可证）
• 你的代码不会被发送到 OpenCode 服务器
• 如果使用第三方 API（如 OpenAI），请遵守其服务条款
• 建议查看公司的代码安全政策

Q6: 如何卸载 OpenCode？

A:

# Homebrew
brew uninstall opencode

# NPM
npm uninstall -g opencode-ai

# 手动删除
rm -rf ~/.local/bin/opencode
rm -rf ~/.config/opencode

# 图形界面：按系统标准应用卸载流程

总结

OpenCode 是一个强大而灵活的 AI 编程助手，无论你是初学者还是资深开发者，都能从中受益。通过本指南，你应该已经成功安装并初步了解了 OpenCode 的基本用法。

关键要点回顾：

• ✅ 选择适合你的安装方式（Homebrew/NPM/脚本）
• ✅ 验证安装成功（opencode --version）
• ✅ 首次运行会自动下载免费模型
• ✅ 支持多种模型（免费 + 付费）
• ✅ 遇到问题参考故障排查章节
• ✅ 探索配置和插件扩展能力

记住：OpenCode 是你的编程助手，不是替代品。最好的使用方式是将其作为提升效率的工具，而不是完全依赖它。保持学习，不断进步！

立即开始你的 AI 编程之旅吧！