快速入门

欢迎来到 Opencode 的世界！本教程将带你在 5 分钟内完成安装、配置并开始你的第一个 AI 编程任务。

1. 安装 Opencode

你可以通过官网下载安装包，也可以使用命令行的包管理器快速安装。

macOS

推荐使用 Homebrew 安装：

brew install anomalyco/tap/opencode

或者下载 .dmg 文件：

  1. 访问 opencode.ai
  2. 下载 macOS 安装包
  3. 拖拽到 Applications 文件夹

Windows

支持多种安装方式：

方法 A：使用 Chocolatey（推荐）

choco install opencode

方法 B：使用 Scoop

scoop bucket add extras
scoop install extras/opencode

方法 C：使用 NPM

npm install -g opencode-ai

方法 D：下载安装包

  1. 访问 opencode.ai
  2. 下载 Windows 安装包（.exe）
  3. 运行安装程序

Linux

Debian/Ubuntu (.deb)

# 下载 .deb 包
wget https://opencode.ai/download/opencode_latest_amd64.deb

# 安装
sudo dpkg -i opencode_latest_amd64.deb

Fedora/RHEL (.rpm)

# 下载 .rpm 包
wget https://opencode.ai/download/opencode_latest.rpm

# 安装
sudo rpm -i opencode_latest.rpm

Arch Linux (使用 Paru)

paru -S opencode-bin

AppImage（通用）

# 下载 AppImage
wget https://opencode.ai/download/opencode_latest.AppImage

# 添加执行权限
chmod +x opencode_latest.AppImage

# 运行
./opencode_latest.AppImage

2. 首次启动

启动 Opencode

macOS/Linux

opencode

Windows

  • 从开始菜单启动
  • 或在命令行运行 opencode

欢迎向导

首次启动时，你将看到欢迎向导：

  1. 选择语言：选择中文或其他语言
  2. 导入设置（可选）：如果你之前使用 VS Code，可以一键导入扩展和快捷键配置
  3. 选择主题：选择你喜欢的界面主题

3. 连接 AI 模型

这是最重要的一步！Opencode 需要连接到 AI 模型才能工作。

方式一：使用 Opencode Zen（推荐新手）

最简单的方式，官方提供免费试用额度：

  1. 在 Opencode 中按 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows)
  2. 输入 /connect 并回车
  3. 选择 Opencode Zen
  4. 访问 https://opencode.ai/auth 创建账号
  5. 复制 API Key 并粘贴到 Opencode
  6. 完成！

方式二：使用现有订阅

如果你已经有 Claude Pro、ChatGPT Plus 等订阅：

  1. 运行 /connect 命令
  2. 选择对应的 Provider：
    • Anthropic - 如果你有 Claude Pro/Max
    • OpenAI - 如果你有 ChatGPT Plus/Pro
    • Google - 如果你有 Gemini 订阅
  3. 按提示完成 OAuth 认证
  4. 完成！

方式三：使用本地模型（完全免费）

如果你想完全免费使用：

  1. 安装 Ollama：访问 ollama.ai
  2. 下载模型：
    ollama pull deepseek-coder
  3. 在 Opencode 中运行 /connect
  4. 选择 Ollama
  5. 完成！

详细配置方法：Provider 配置完全指南

4. 编写第一行代码

现在让我们测试 Opencode 的 AI 能力！

方法一：Inline Edit（快速修改）

  1. 创建一个新文件 hello.py
  2. 按 Cmd+K (macOS) 或 Ctrl+K (Windows)
  3. 输入："写一个函数计算斐波那契数列"
  4. 按回车，观察 AI 如何生成代码

方法二：Chat 模式（对话式开发）

  1. 按 Cmd+L (macOS) 或 Ctrl+L (Windows) 打开聊天面板
  2. 输入你的需求：
    帮我创建一个 React 计数器组件，包含：
- 增加按钮
- 减少按钮
- 重置按钮
- 显示当前计数
  3. AI 会生成代码并询问是否应用
  4. 点击"应用"或按 Cmd+Enter

方法三：Plan & Build 模式（复杂任务）

这是 Opencode 最强大的功能！

  1. 按 Tab 键切换到 Plan 模式
  2. 描述你的需求：
    我要创建一个 Python 贪吃蛇游戏，要求：
- 使用 pygame 库
- 支持方向键控制
- 显示分数
- 游戏结束后可以重新开始
  3. AI 会给出详细的实施计划
  4. 确认计划后，再按 Tab 进入 Build 模式
  5. AI 会自动创建文件并实现功能

详细了解：Plan & Build 模式详解

5. 验证安装成功

检查版本

opencode --version

应该显示版本号，例如：v1.0.150 或更高

测试 AI 功能

创建一个测试文件并尝试生成代码：

  1. 创建 test.js
  2. 按 Cmd+K / Ctrl+K
  3. 输入："写一个函数反转字符串"
  4. 如果 AI 成功生成代码，说明一切正常！

常见问题

Q: 提示 "No model configured"

A: 需要先连接 AI 模型，运行 /connect 命令

Q: 启动很慢或卡顿

A: 可能是监控了大型目录（如 node_modules），参考 性能优化

Q: 无法连接到模型

A: 检查：

  1. 网络连接是否正常
  2. API Key 是否正确
  3. 是否有足够的配额

详细排查：Provider 认证问题

Q: 命令找不到

A: 确保 Opencode 已添加到 PATH：

  • macOS/Linux: 检查 ~/.zshrc 或 ~/.bashrc
  • Windows: 检查系统环境变量

6. 创建你的第一个项目

初始化项目

  1. 创建项目文件夹：

    mkdir my-first-ai-project
cd my-first-ai-project

  2. 在 Opencode 中打开：

    opencode .

  3. 运行 /init 命令初始化项目

  4. Opencode 会创建 AGENTS.md 文件，这是 AI 理解你项目的关键

配置项目规范

编辑 AGENTS.md，告诉 AI 你的项目规范：

# 项目规范

## 技术栈
- 语言：Python 3.10+
- 框架：Flask
- 数据库：SQLite

## 编码规范
- 使用 Black 格式化代码
- 函数名使用 snake_case
- 类名使用 PascalCase

## 目录结构
- `/app` - 应用代码
- `/tests` - 测试文件
- `/docs` - 文档

现在 AI 会记住这些规范，每次生成代码都会遵循！

详细了解：智能体与 AGENTS.md

7. 下一步学习

基础技能（1-2 天）

进阶配置（3-5 天）

高级应用（1-2 周）

8. 实用技巧

快捷键速查

功能macOSWindows/Linux
Inline EditCmd+KCtrl+K
Chat 面板Cmd+LCtrl+L
命令面板Cmd+Shift+PCtrl+Shift+P
切换模式TabTab

常用命令

  • /connect - 连接 AI 模型
  • /init - 初始化项目
  • /models - 切换模型
  • /undo - 撤销修改
  • /share - 分享会话

提示词技巧

好的提示词示例：

✅ 创建一个 React 组件，使用 TypeScript，包含状态管理和错误处理

❌ 写个组件

详细学习：Prompt 工程指南

9. 获取帮助

文档资源

社区支持

🎉 恭喜你完成了 Opencode 的快速入门！现在开始享受 AI 编程的乐趣吧！

如有问题，随时查阅文档或在社区提问。祝你编程愉快！

最近更新: