Open Code教程（一）| 快速入门：安装配置与基础使用

OpenCode 快速入门：安装配置与基础使用
- 一、什么是 OpenCode
- - 核心特点
  - 开发团队
  - 发布时间线
  - 相关开源项目
- 二、OpenCode vs Claude Code 对比
- - 选择建议
- 三、网络环境说明
- - 需要科学上网
  - 无需科学上网
- 四、安装 OpenCode
- - Windows 安装
  - - CLI 版本（推荐）
    - 桌面应用
  - macOS 安装
  - - CLI 版本
    - 桌面应用
  - Linux 安装
  - - CLI 版本
    - 桌面应用
  - 验证安装
- 五、配置 AI 提供商
- - 方式一：OpenCode Zen（新手推荐）
  - 方式二：DeepSeek（国内推荐）
  - 方式三：Anthropic Claude
  - 方式四：环境变量配置
  - 查看可用模型
- 六、第一次使用
- - 启动 OpenCode
  - 初始化项目（推荐）
  - 开始对话
  - 基础命令速查
  - Plan 模式 vs Build 模式
- 七、常见问题
- - Q: 安装时下载很慢怎么办？
  - Q: 提示 "command not found" 怎么办？
  - Q: Windows 上如何安装 CLI 版本？
  - Q: API Key 存储在哪里？
  - Q: 如何更新 OpenCode？
  - Q: 如何卸载 OpenCode？
  - Q: 代码会上传到云端吗？
- 下一篇预告
- 相关资源

OpenCode 快速入门：安装配置与基础使用

一、什么是 OpenCode

OpenCode 是一个开源的 AI 编程助手，可以在终端或桌面应用中运行。
官网文档：https://opencode.ai/docs
你可以把它想象成一个随时待命的高级开发者，帮助你：

✍️ 编写和调试代码
📖 理解现有代码库
🔄 重构和优化代码
❓ 回答技术问题
🤖 自动化重复任务

核心特点

特性	说明
100% 开源免费	无隐藏费用，代码完全开源
75+ 模型支持	Claude、GPT、Gemini、DeepSeek、本地模型等
多种运行方式	CLI 终端、桌面应用、IDE 扩展
IDE 集成	支持 VS Code、Cursor 等
GitHub 集成	可直接处理 Issue 和 PR

开发团队

OpenCode 由SST（Serverless Stack）团队开发：

公司：SST，美国旧金山
创始人：Jay V、Frank Wang（2017 年创立）
核心维护者：Dax Raad
投资人：Reid Hoffman（LinkedIn 创始人）、Max Levchin（PayPal 创始人）、Steve Chen（YouTube 创始人）等

发布时间线

时间	事件
2017 年	SST 公司成立
2021 年 7 月	SST 获得 Y Combinator 投资
2025 年 7 月 11 日	OpenCode 正式发布
2025 年 9 月 29 日	OpenCode Zen 发布（官方优化模型）
2025 年中期	经历重大重写，功能更加成熟
2026 年 1 月	GitHub Stars 约 69,800，持续增长中

二、OpenCode vs Claude Code 对比

很多人会问：OpenCode 和 Claude Code 有什么区别？

对比项	OpenCode	Claude Code
开源	✅ 完全开源	❌ 闭源
价格	✅ 免费（需自备 API）	需要 Claude Pro/Max 订阅
模型支持	✅ 75+ 提供商	❌ 仅 Claude
本地模型	✅ 支持 Ollama 等	❌ 不支持
功能完善度	持续迭代中	更成熟
桌面应用	✅ 有（BETA）	❌ 无

选择建议

已有 Claude Pro/Max 订阅 → 两者都可以用
想用 GPT、DeepSeek 等其他模型 → 选 OpenCode
注重隐私，想用本地模型 → 选 OpenCode
预算有限 → 选 OpenCode
Windows 用户想要图形界面 → 选 OpenCode 桌面应用

三、网络环境说明

⚠️国内用户请注意：在开始之前，请了解网络访问要求。

需要科学上网

场景	说明
下载安装 OpenCode	GitHub 和 opencode.ai 在国内访问可能不稳定
使用 OpenAI API	OpenAI API 在国内无法直接访问
使用 Anthropic API	Claude API 在国内无法直接访问
使用 Google Gemini	Google 服务在国内无法访问
使用 GitHub Copilot	GitHub 服务可能不稳定

无需科学上网

场景	说明
使用 DeepSeek API	✅ 国产模型，国内可直接访问
使用阿里通义千问	✅ 国产模型，国内可直接访问
使用本地模型（Ollama）	✅ 完全本地运行，无需网络
使用国内 API 代理服务	✅ 通过代理访问海外模型

建议：如果你在国内且没有稳定的科学上网环境，推荐使用DeepSeek或本地模型（Ollama）。

四、安装 OpenCode

OpenCode 提供两种版本：

版本	说明	适合人群
CLI（命令行）	在终端中运行，可与 IDE 集成	熟悉命令行的开发者
桌面应用（BETA）	独立窗口应用，下载即用	喜欢图形界面的用户

两者功能完全相同，选择你喜欢的方式即可。

Windows 安装

CLI 版本（推荐）

需要先安装 Node.js，然后运行：

npm install-g opencode-ai

安装完成后运行opencode --version验证。

桌面应用

访问 opencode.ai/download
下载 Windows 版本（opencode-desktop-windows-x64.exe）
双击运行安装
从开始菜单启动 OpenCode

macOS 安装

CLI 版本

方式一：安装脚本（推荐）

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

安装完成后，如果提示command not found，请重新打开终端或执行source ~/.zshrc。

方式二：npm 安装

npminstall-g opencode-ai

方式三：Homebrew 安装

brewinstallopencode

桌面应用

从 opencode.ai/download 下载对应版本：

芯片	下载文件
Apple Silicon (M1/M2/M3/M4)	`opencode-desktop-darwin-aarch64.dmg`
Intel	`opencode-desktop-darwin-x64.dmg`

Linux 安装

CLI 版本

方式一：安装脚本（推荐）

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

安装完成后，如果提示command not found，请重新打开终端或执行source ~/.bashrc。

方式二：npm 安装

npminstall-g opencode-ai

桌面应用

从 GitHub Releases 下载：

格式	适用发行版
`.deb`	Ubuntu、Debian 等
`.rpm`	Fedora、CentOS、RHEL 等
`AppImage`	通用，无需安装，直接运行

验证安装

安装完成后，打开终端运行：

opencode --version

如果显示版本号（如1.1.21），说明安装成功。

五、配置 AI 提供商

OpenCode 支持 75+ AI 提供商，首次使用需要配置。

方式一：OpenCode Zen（新手推荐）

OpenCode 官方提供的模型服务，配置最简单：

启动 OpenCode
输入/connect
选择opencode
浏览器会打开 opencode.ai/auth
登录并获取 API Key
粘贴 API Key 到终端

方式二：DeepSeek（国内推荐）

DeepSeek 是国产模型，国内可直接访问，性价比高：

访问 platform.deepseek.com 注册账号
创建 API Key
启动 OpenCode，输入/connect
选择DeepSeek
粘贴 API Key

方式三：Anthropic Claude

如果你有 Claude Pro/Max 订阅：

启动 OpenCode，输入/connect
选择Anthropic
选择Claude Pro/Max
浏览器会打开，完成 OAuth 认证

方式四：环境变量配置

也可以通过环境变量配置（适合自动化场景）：

macOS / Linux：

# Anthropic ClaudeexportANTHROPIC_API_KEY="your-key-here"# OpenAIexportOPENAI_API_KEY="your-key-here"# DeepSeekexportDEEPSEEK_API_KEY="your-key-here"

添加到~/.bashrc（Linux）或~/.zshrc（macOS）后，执行source命令生效。

Windows（PowerShell）：

# 临时设置（当前会话有效）$env:DEEPSEEK_API_KEY="your-key-here"# 永久设置（需要管理员权限）[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY","your-key-here","User")

查看可用模型

配置完成后，输入/models查看可用模型列表，选择你想使用的模型。

六、第一次使用

启动 OpenCode

# 进入你的项目目录cdyour-project# 启动 OpenCodeopencode

桌面应用用户直接打开应用，然后选择项目目录。

初始化项目（推荐）

首次使用某个项目时，建议运行：

/init

这会让 OpenCode 分析项目结构，生成AGENTS.md文件，帮助 AI 更好地理解你的项目。

开始对话

直接输入你的问题：

这个项目是做什么的？帮我解释一下项目结构

OpenCode 会分析代码并给出回答。

基础命令速查

命令	功能
`/help`	显示帮助
`/models`	查看/切换模型
`/connect`	配置 AI 提供商
`/init`	初始化项目
`/new`	开始新会话
`/undo`	撤销上次修改
`/redo`	重做撤销的修改
`/compact`	压缩会话（节省 Token）
`/share`	分享当前会话
`/sessions`	查看历史会话
`/theme`	切换主题
`/exit`	退出
`Tab`	切换 Plan/Build 模式

Plan 模式 vs Build 模式

OpenCode 有两种工作模式，按Tab键切换：

模式	说明	适用场景
Plan	只分析，不修改代码	规划复杂功能、代码审查
Build	直接修改代码（默认）	实际编码、修复 bug

建议：复杂功能先用 Plan 模式规划，确认方案后再切换到 Build 模式实现。

七、常见问题

Q: 安装时下载很慢怎么办？

使用科学上网
直接从 GitHub Releases 下载二进制文件
Windows 用户推荐使用桌面应用

Q: 提示 “command not found” 怎么办？

原因：安装目录未添加到 PATH 环境变量。

解决方法：

# 方法一：重新打开终端# 方法二：手动加载配置source~/.bashrc# Linux (bash)source~/.zshrc# macOS / Linux (zsh)# 方法三：检查安装目录是否在 PATH 中echo$PATH|grep-E"(opencode|\.local/bin)"# 方法四：手动添加到 PATH（以 ~/.opencode/bin 为例）echo'export PATH="$HOME/.opencode/bin:$PATH"'>>~/.bashrcsource~/.bashrc

Q: Windows 上如何安装 CLI 版本？

推荐使用 npm 安装（需要先安装 Node.js）：

npm install-g opencode-ai

或者使用桌面应用（功能完全相同）。

Q: API Key 存储在哪里？

通过/connect添加的凭证存储在：

~/.local/share/opencode/auth.json

Q: 如何更新 OpenCode？

方式一：使用 upgrade 命令（推荐）

opencode upgrade

方式二：npm 更新

npmupdate -g opencode-ai

方式三：重新运行安装脚本（macOS / Linux）

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

方式四：Homebrew（macOS）

brew upgrade opencode

桌面应用：重新下载最新版本安装即可。

Q: 如何卸载 OpenCode？

opencode uninstall

这会删除 OpenCode 及相关文件。你也可以添加参数保留配置或数据：

# 保留配置文件opencode uninstall --keep-config# 保留会话数据opencode uninstall --keep-data

Q: 代码会上传到云端吗？

OpenCode 本身不存储你的代码。但当你使用云端 AI 提供商（如 Claude、GPT）时，提示词和相关代码片段会发送到对应的 API。如果你注重隐私，可以使用本地模型（Ollama）。

下一篇预告

本文介绍了 OpenCode 的安装、配置和基础使用。下一篇《OpenCode 命令与技巧大全》将详细介绍所有命令、快捷键和使用技巧。