OpenCode 零基础入门指南

OpenCode 零基础入门指南

目标读者：零编程基础的新手
阅读时间：约 15 分钟
完成效果：成功安装并配置 OpenCode，开始 AI 编程之旅

一、什么是 OpenCode？

OpenCode 是一款 AI 编程助手，让你通过自然语言对话就能完成代码编写、调试和项目管理。

核心功能

• 智能编程：用中文描述需求，自动生成代码
• 代码调试：自动检测错误并提供修复建议
• 项目管理：自动分析项目结构，理解上下文
• 免费可用：支持免费模型，也可接入更强大的付费模型

术语解释

二、5 分钟快速开始

步骤 1：安装 Node.js

1. 访问 Node.js 官网下载 LTS 版本（长期支持版）
2. 双击安装包，一路点击"下一步"直到完成
3. 安装完成后重启终端

步骤 2：安装 OpenCode

打开终端（Windows 按 Win + R，输入 cmd 回车），执行：

npm install -g opencode-ai@latest

步骤 3：验证安装

opencode --version

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

步骤 4：启动使用

opencode

首次启动会提示选择模型，可以选择免费模型直接开始体验。

三、环境准备

系统要求

• Windows: Windows 10 或更高版本
• macOS: macOS 10.15 或更高版本
• Linux: 主流发行版均可

安装 Node.js（版本 >= 22.0）

方法 A：直接下载安装（推荐新手）

1. 访问 Node.js 官网下载 LTS 版本
2. 双击安装包，一路点击"下一步"直到完成
3. 安装完成后重启终端

方法 B：使用 nvm 安装（进阶用户）

# 安装指定版本的 Node.js
nvm install 22.22.0

# 使用这个版本
nvm use 22.22.0

# 验证安装
node --version

nvm 说明：nvm 是 Node Version Manager 的缩写，用于管理多个 Node.js 版本。

四、安装 OpenCode

4.1 正式安装

在终端中执行：

npm install -g opencode-ai@latest

提示：-g 表示全局安装，安装后可以在任何地方使用 opencode 命令。

安装过程可能需要 1-3 分钟，取决于网络速度。

4.2 验证安装

opencode --version

4.3 启动 OpenCode

opencode

首次启动会显示模型选择界面，可选择免费模型开始体验。

五、配置自定义模型

5.1 为什么要配置自定义模型？

官方免费模型虽然能用，但可能响应速度较慢或有额度限制。通过配置自定义模型，可以：

• 获得更快的响应速度
• 使用更强大的模型
• 提高使用额度

5.2 配置步骤

第 1 步：获取 API Key

从合法渠道获取 API Key（格式：sk-xxxxxx）。

第 2 步：修改配置文件

找到配置文件：

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

如何快速打开？
Windows 用户按 Win + R，输入 %APPDATA%\opencode，回车即可打开文件夹。

在 provider 字段中添加：

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://你的API地址/v1"
      }
    }
  }
}

重要提示：

• 大部分服务需要在 URL 后面加 /v1
• 示例地址格式：https://example.com/v1

第 3 步：选择模型

在配置文件中设置默认模型：

{
  "model": "anthropic/claude-sonnet-4"
}

不同服务商的模型名称可能不同，请咨询你的 API 提供商。

第 4 步：验证配置

重启 OpenCode，随便问个问题测试：

opencode

如果能正常回复，说明配置成功。

六、安装增强插件

6.1 什么是 Oh My OpenCode？

Oh My OpenCode 是 OpenCode 的增强插件，安装后可以：

• 多 AI 协作：同时调用多个 AI 模型
• 专业智能体：内置前端工程师、架构师等专业角色
• 提示词优化：自动优化你的指令
• 并行任务：同时执行多个任务

6.2 安装插件

npm install -g oh-my-opencode

6.3 配置插件

在 opencode.json 中添加：

{
  "plugin": [
    "oh-my-opencode"
  ]
}

6.4 验证安装

启动 OpenCode，执行 /help 查看新增的命令列表。

七、Skills 技能详解

7.1 什么是 Skills？

Skills 是 OpenCode 的"技能卡"，装上之后 OpenCode 就能拥有特定的专业能力。

例如：

• 装了前端技能，OpenCode 就能帮你设计界面
• 装了后端技能，OpenCode 就能帮你设计数据库结构
• 装了计划技能，OpenCode 就能帮你制定项目计划

7.2 Skills 的三种安装方式

方式一：全局安装（推荐新手）

全局安装的 skill 可以在任何项目中使用。

安装路径：

• Windows: C:\Users\你的用户名\.config\opencode\skills\
• macOS/Linux: ~/.config/opencode/skills/

目录结构示例：

~/.config/opencode/skills/
├── frontend-ui-ux/           # 前端 UI/UX 设计技能
│   └── SKILL.md
├── backend-design/           # 后端设计技能
│   └── SKILL.md
└── writing-plans/            # 编写计划技能
    └── SKILL.md

安装步骤：

1. 打开 skills 目录（如果不存在就新建）
2. 创建 skill 文件夹（如 my-skill）
3. 在文件夹内创建 SKILL.md 文件
4. 重启 OpenCode 即可生效

方式二：项目级安装

只在特定项目中生效。

安装路径：在你的项目根目录下创建 .opencode/skills/

特点：

• 优先级高于全局 skill
• 可以随项目一起提交到 Git
• 团队成员共享相同的 skill 配置

方式三：多编辑器同步（推荐团队使用）

如果同时使用多个 AI 编辑器，可以通过软链接让 skill 配置在所有编辑器中同步。

操作步骤（Windows 示例）：

1. 在 ~/.claude/skills 目录下存放所有 skill
2. 创建符号链接让其他编辑器共享：

# 让 Cursor 共享 skills
New-Item -ItemType Junction -Path "$HOME\.cursor\rules\skills" -Target "$HOME\.claude\skills"

# 让 OpenCode 共享 skills
New-Item -ItemType Junction -Path "$HOME\.config\opencode\skills" -Target "$HOME\.claude\skills"

优势：

• 一处更新，处处生效
• 避免重复配置
• 团队统一规范

7.3 如何获取 Skills？

可以在以下地方寻找现成的 skill：

• 开源社区搜索
• OpenCode 官方文档
• 技术社区分享

自己编写 Skills

如果想创建自己的 skill，只需要：

1. 创建一个文件夹（如 my-skill）
2. 在里面创建 SKILL.md 文件
3. 按照规范编写 skill 内容

SKILL.md 基本结构：

# Skill 名称

## 描述
这个 skill 用来做什么...

## 使用场景
- 场景1：...
- 场景2：...

## 指令模板
当用户要求 XXX 时，你应该...

## 示例
输入：...
输出：...

7.4 常用 Skills 推荐

7.5 验证 Skills 是否生效

1. 重启 OpenCode
2. 执行 /skills 查看已加载的 skills 列表
3. 尝试使用 skill 的功能，看是否符合预期

八、常见问题 FAQ

Q1: 提示 “Unable to connect”

原因：网络连接问题，可能是代理或防火墙导致。

解决方法：

如果使用了代理软件，需要在终端中设置代理：

# Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"

# 或者直接在启动时指定
opencode --proxy http://127.0.0.1:7890

Q2: 找不到 opencode.json 配置文件

原因：首次使用，配置文件尚未创建。

解决方法：

手动创建配置文件：

1. 打开文件夹：C:\Users\你的用户名\.config\opencode\（Windows）
2. 如果不存在，新建 .config 和 opencode 文件夹
3. 新建文件 opencode.json
4. 粘贴基础配置：

{
  "$schema": "https://opencode.ai/config.json"
}

Q3: 如何切换模型？

在 OpenCode 中执行：

/models

然后按提示选择你想使用的模型。

Q4: 安装时出现权限错误

原因：没有管理员权限。

解决方法：

# Windows：以管理员身份运行 PowerShell
# 右键点击 PowerShell → 以管理员身份运行

# macOS/Linux：使用 sudo
sudo npm install -g opencode-ai@latest

Q5: 如何卸载 OpenCode？

npm uninstall -g opencode-ai

Q6: 如何查看已安装的版本？

npm list -g opencode-ai

九、参考资源

官方文档

• 英文官网：搜索 “OpenCode AI”
• 中文文档：搜索 “OpenCode Guide”
• GitHub 仓库：搜索 “anomalyco opencode”

插件资源

• Oh My OpenCode：搜索 “code-yeongyu oh-my-opencode”

学习资源

• Node.js 官方
• npm 文档

下一步？

恭喜你完成 OpenCode 的安装配置！

现在你可以：

1. 开始第一个项目：在任意文件夹执行 opencode，让 AI 帮你写代码
2. 学习更多命令：执行 /help 查看所有可用命令
3. 配置 Skills：安装更多技能，扩展 OpenCode 的能力
4. 加入社区：参与技术讨论，分享使用心得

最后更新时间：2025年3月
文档版本：v1.0
如有问题：欢迎在评论区留言讨论

本文档仅供学习交流使用，请遵守相关服务条款。