490 lines
15 KiB
Markdown
490 lines
15 KiB
Markdown
---
|
||
title: OpenCode
|
||
date: 2026-06-13 10:34:02
|
||
tags:
|
||
---
|
||
|
||
# OpenCode 安装指南
|
||
|
||
## Windows 安装方式
|
||
|
||
### 方式一：使用 npm 安装（推荐）
|
||
|
||
1. 确保已安装 Node.js（建议版本 16 或更高）
|
||
2. 打开 PowerShell 或命令提示符
|
||
3. 运行以下命令进行全局安装：
|
||
```bash
|
||
npm i -g opencode-ai
|
||
```
|
||
4. 安装完成后，可以通过以下命令验证安装：
|
||
```bash
|
||
opencode --version
|
||
```
|
||
|
||
### 方式二：使用 curl 安装（需要 WSL 或 Git Bash）
|
||
|
||
如果您使用的是 Windows Subsystem for Linux (WSL) 或 Git Bash，可以使用以下命令：
|
||
|
||
```bash
|
||
curl -fsSL https://opencode.ai/install | bash
|
||
```
|
||
|
||
**注意：** 此方式需要在 Unix-like 环境中运行，Windows 原生的命令提示符或 PowerShell 不支持此命令。
|
||
|
||
## 其他操作系统安装方式
|
||
|
||
### Linux/macOS
|
||
|
||
```bash
|
||
curl -fsSL https://opencode.ai/install | bash
|
||
```
|
||
|
||
或使用 npm：
|
||
|
||
```bash
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### PowerShell 中使用 curl 安装后命令不识别
|
||
|
||
**问题描述：** 在 PowerShell 中运行 `curl -fsSL https://opencode.ai/install | bash` 后，`opencode` 命令无法识别。
|
||
|
||
**原因分析：**
|
||
1. PowerShell 中的 `curl` 是 `Invoke-WebRequest` 的别名，不是真正的 curl
|
||
2. `bash` 命令在 PowerShell 中不可用（除非安装了 WSL 或 Git Bash）
|
||
3. 即使安装成功，安装路径可能不在 Windows PATH 中
|
||
|
||
**解决方案：**
|
||
|
||
#### 方案一：使用 npm 安装（推荐）
|
||
```bash
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
#### 方案二：在 WSL 或 Git Bash 中安装
|
||
1. 打开 WSL 或 Git Bash
|
||
2. 运行安装命令：
|
||
```bash
|
||
curl -fsSL https://opencode.ai/install | bash
|
||
```
|
||
3. 如果仍然不识别，检查安装路径并添加到 PATH
|
||
|
||
#### 方案三：手动添加 PATH
|
||
如果已安装但命令不识别：
|
||
1. 找到安装位置（通常在 `~/.local/bin` 或 `/usr/local/bin`）
|
||
2. 将路径添加到 Windows PATH：
|
||
```powershell
|
||
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\path\to\opencode", "User")
|
||
```
|
||
3. 重启 PowerShell
|
||
|
||
### nvm 用户切换 Node.js 版本后 opencode 不可用
|
||
|
||
**问题描述：** 使用 nvm（Node Version Manager）管理 Node.js 版本时，切换版本后之前全局安装的 opencode 命令无法识别。
|
||
|
||
**原因分析：**
|
||
nvm 为每个 Node.js 版本维护独立的全局包目录。当您切换 Node.js 版本时：
|
||
- 每个版本有自己独立的 `node_modules` 目录
|
||
- 之前版本安装的全局包在新版本中不可用
|
||
- 需要重新安装全局包
|
||
|
||
**解决方案：**
|
||
|
||
#### 方案一：为当前版本重新安装（推荐）
|
||
```bash
|
||
# 切换到目标 Node.js 版本
|
||
nvm use 18
|
||
|
||
# 重新安装 opencode
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
#### 方案二：使用 nvm 的默认包迁移功能
|
||
```bash
|
||
# 设置默认 Node.js 版本
|
||
nvm alias default 18
|
||
|
||
# 重新安装全局包
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
#### 方案三：使用 nvm 的 --default-packages 参数
|
||
在安装 Node.js 版本时指定默认包：
|
||
```bash
|
||
# 设置默认包列表
|
||
echo "opencode-ai" > ~/.nvm/default-packages
|
||
|
||
# 安装新版本时会自动安装默认包
|
||
nvm install 18
|
||
```
|
||
|
||
#### 方案四：检查当前 Node.js 版本
|
||
```bash
|
||
# 查看当前使用的 Node.js 版本
|
||
node --version
|
||
|
||
# 查看 nvm 列表
|
||
nvm list
|
||
|
||
# 切回之前安装 opencode 的版本
|
||
nvm use <之前版本号>
|
||
```
|
||
|
||
**最佳实践：**
|
||
1. 在切换版本后检查全局包：`npm list -g --depth=0`
|
||
2. 为常用版本安装 opencode：`nvm use <版本> && npm i -g opencode-ai`
|
||
3. 考虑使用 `nvm alias default <版本>` 设置默认版本
|
||
|
||
#### 方案五：配置独立的全局包目录（一劳永逸）
|
||
|
||
将 npm 全局包目录设置到固定位置，不依赖于 nvm 管理的 Node.js 版本：
|
||
|
||
```bash
|
||
# 1. 创建全局包目录
|
||
mkdir -p ~/.npm-global
|
||
|
||
# 2. 配置 npm 使用新目录
|
||
npm config set prefix ~/.npm-global
|
||
|
||
# 3. 添加到 PATH（添加到 ~/.bashrc 或 ~/.zshrc）
|
||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
|
||
# 4. 安装 opencode
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
**优点：**
|
||
- 所有 Node.js 版本共享同一套全局包
|
||
- 切换版本后无需重新安装
|
||
- 一次安装，永久可用
|
||
|
||
**注意：** 如果遇到包兼容性问题，可以删除 `~/.npm-global` 目录并重新配置。
|
||
|
||
#### 方案六：使用 nvm 的 reinstall-packages 迁移包
|
||
|
||
如果已经在某个版本下安装了 opencode，可以迁移到其他版本：
|
||
|
||
```bash
|
||
# 查看当前版本
|
||
nvm current
|
||
|
||
# 切换到目标版本
|
||
nvm use 18
|
||
|
||
# 将之前版本的全局包迁移到当前版本
|
||
nvm reinstall-packages <源版本号>
|
||
```
|
||
|
||
例如：`nvm reinstall-packages 16.20.0` 将 16.20.0 版本的全局包迁移到当前版本。
|
||
|
||
### 权限问题
|
||
如果在 Linux/macOS 上遇到权限错误，请使用 `sudo`：
|
||
```bash
|
||
sudo npm i -g opencode-ai
|
||
```
|
||
|
||
### 网络问题
|
||
如果下载速度慢，可以尝试使用镜像源：
|
||
```bash
|
||
npm config set registry https://registry.npmmirror.com
|
||
npm i -g opencode-ai
|
||
```
|
||
|
||
## 验证安装
|
||
|
||
安装完成后，运行以下命令验证：
|
||
```bash
|
||
opencode --version
|
||
```
|
||
|
||
如果显示版本号，则表示安装成功。
|
||
|
||
## 迁移 OpenCode 配置
|
||
|
||
当需要在新机器上恢复 OpenCode 配置时，可以使用以下方法迁移。
|
||
|
||
### 源机器打包
|
||
|
||
在源机器上打包 OpenCode 配置文件和目录：
|
||
|
||
##### Linux/macOS
|
||
|
||
```bash
|
||
tar -czf opencode-migration.tar.gz -C ~ \
|
||
.config/opencode/opencode.json \
|
||
.config/opencode/oh-my-openagent.json \
|
||
.config/opencode/AGENTS.md \
|
||
.agents/ \
|
||
.local/share/opencode/auth.json \
|
||
.cache/oh-my-opencode/connected-providers.json
|
||
```
|
||
|
||
**打包内容说明：**
|
||
|
||
- `opencode.json`：OpenCode 主配置文件
|
||
- `oh-my-openagent.json`：Oh My OpenAgent 配置
|
||
- `AGENTS.md`：Agent 指令文件
|
||
- `~/.agents/`：自定义 Agent 和 Skill 目录
|
||
- `auth.json`：认证信息（登录状态等）
|
||
- `connected-providers.json`：已连接的 Provider 配置
|
||
|
||
### 新机器恢复
|
||
|
||
在新机器上恢复配置：
|
||
|
||
```bash
|
||
# 解压配置文件到用户目录
|
||
tar -xzf opencode-migration.tar.gz -C ~/
|
||
|
||
# 进入 OpenCode 配置目录并安装依赖
|
||
cd ~/.config/opencode && npm install
|
||
```
|
||
|
||
### 迁移后验证
|
||
|
||
```bash
|
||
# 验证 OpenCode 版本
|
||
opencode --version
|
||
|
||
# 检查配置文件是否正确恢复
|
||
ls -la ~/.config/opencode/
|
||
|
||
# 测试 Agent 是否正常
|
||
opencode agent list
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
- **认证信息**：`auth.json` 包含登录凭证，迁移后可能需要重新登录
|
||
- **路径差异**：如果新机器用户名不同，需要调整配置文件中的路径
|
||
- **依赖版本**：建议在新机器上使用相同或更新的 Node.js 版本
|
||
- **权限问题**：确保解压后的文件权限正确（`chmod 600 ~/.local/share/opencode/auth.json`）
|
||
|
||
### Windows 系统迁移
|
||
|
||
Windows 下的 OpenCode 配置文件路径与 Linux/macOS 不同，需要使用 PowerShell 命令进行迁移。
|
||
|
||
#### 源机器打包（PowerShell）
|
||
|
||
```powershell
|
||
# 创建临时目录存放配置文件
|
||
$tempDir = "$env:TEMP\opencode-migration"
|
||
New-Item -ItemType Directory -Path $tempDir -Force
|
||
|
||
# 复制配置文件到临时目录
|
||
Copy-Item "$env:USERPROFILE\.config\opencode\opencode.json" $tempDir -ErrorAction SilentlyContinue
|
||
Copy-Item "$env:USERPROFILE\.config\opencode\oh-my-openagent.json" $tempDir -ErrorAction SilentlyContinue
|
||
Copy-Item "$env:USERPROFILE\.config\opencode\AGENTS.md" $tempDir -ErrorAction SilentlyContinue
|
||
Copy-Item "$env:USERPROFILE\.agents" "$tempDir\.agents" -Recurse -ErrorAction SilentlyContinue
|
||
Copy-Item "$env:USERPROFILE\.local\share\opencode\auth.json" $tempDir -ErrorAction SilentlyContinue
|
||
Copy-Item "$env:USERPROFILE\.cache\oh-my-opencode\connected-providers.json" $tempDir -ErrorAction SilentlyContinue
|
||
|
||
# 压缩为 zip 文件
|
||
Compress-Archive -Path "$tempDir\*" -DestinationPath "$env:USERPROFILE\Desktop\opencode-migration.zip"
|
||
|
||
# 清理临时目录
|
||
Remove-Item -Path $tempDir -Recurse -Force
|
||
|
||
Write-Host "配置已打包到: $env:USERPROFILE\Desktop\opencode-migration.zip"
|
||
```
|
||
|
||
#### 新机器恢复（PowerShell）
|
||
|
||
```powershell
|
||
# 解压配置文件
|
||
$zipPath = "$env:USERPROFILE\Desktop\opencode-migration.zip"
|
||
$extractPath = "$env:USERPROFILE"
|
||
|
||
Expand-Archive -Path $zipPath -DestinationPath $extractPath -Force
|
||
|
||
# 进入 OpenCode 配置目录并安装依赖
|
||
Set-Location "$env:USERPROFILE\.config\opencode"
|
||
npm install
|
||
|
||
Write-Host "配置恢复完成！"
|
||
```
|
||
|
||
#### Windows 配置文件路径
|
||
|
||
| 文件/目录 | Windows 路径 |
|
||
| ---------- | ----------------------------------------------- |
|
||
| 主配置目录 | `%USERPROFILE%\.config\opencode\` |
|
||
| Agent 目录 | `%USERPROFILE%\.agents\` |
|
||
| 认证信息 | `%USERPROFILE%\.local\share\opencode\auth.json` |
|
||
| 缓存目录 | `%USERPROFILE%\.cache\oh-my-opencode\` |
|
||
|
||
#### 验证迁移（PowerShell）
|
||
|
||
```powershell
|
||
# 检查配置文件是否存在
|
||
Test-Path "$env:USERPROFILE\.config\opencode\opencode.json"
|
||
Test-Path "$env:USERPROFILE\.agents"
|
||
|
||
# 查看配置目录内容
|
||
Get-ChildItem "$env:USERPROFILE\.config\opencode\"
|
||
|
||
# 验证 OpenCode 版本
|
||
opencode --version
|
||
```
|
||
|
||
#### 使用 tar 命令（Windows 10+）
|
||
|
||
Windows 10 及更高版本内置了 tar 命令，也可以使用与 Linux/macOS 相同的方式：
|
||
|
||
```powershell
|
||
# 打包
|
||
tar -czf opencode-migration.tar.gz -C $env:USERPROFILE .config/opencode/opencode.json .config/opencode/oh-my-openagent.json .config/opencode/AGENTS.md .agents .local/share/opencode/auth.json .cache/oh-my-opencode/connected-providers.json
|
||
|
||
# 解压
|
||
tar -xzf opencode-migration.tar.gz -C $env:USERPROFILE
|
||
```
|
||
|
||
#### 注意事项
|
||
|
||
- **路径分隔符**：Windows 使用反斜杠 `\`，但 PowerShell 也支持正斜杠 `/`
|
||
- **权限**：确保对配置目录有读写权限
|
||
- **隐藏文件**：`.config`、`.agents` 等是隐藏目录，需显示隐藏文件才能看到
|
||
- **npm 依赖**：恢复后需运行 `npm install` 安装依赖
|
||
|
||
|
||
|
||
# OpenCode 插件
|
||
|
||
## oh-my-openagent 使用教程
|
||
|
||
**Oh My OpenAgent**（简称 **OmO**）是一个开源的 AI 编程助手增强插件，前身叫 `oh-my-opencode`。
|
||
|
||
oh-my-openagent 运行在 OpenCode这个 AI 编程工具之上，把它变成一个由 **11 个专业 AI Agent** 组成的开发团队。
|
||
|
||
用一句话解释：
|
||
|
||
> **你发一个需求 → OmO 自动调度多个 AI 并行工作 → 比单个 AI 快数倍**
|
||
|
||
目前在 GitHub 上有 **54k+ Stars**，是最受欢迎的 OpenCode 插件。
|
||
|
||
- Github 地址：https://github.com/code-yeongyu/oh-my-openagent
|
||
- 官网：https://ohmyopenagent.com/zh
|
||
|
||
### 安装
|
||
|
||
将以下提示词复制粘贴到你的大模型工具（ OpenCode、Claude Code、AmpCode、Cursor 等）：
|
||
|
||
```
|
||
按照此链接说明安装并配置 oh-my-opencode：https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
|
||
```
|
||
|
||
执行后，它就会自己安装好，安装过程可能有 API key 的配置选项，可以选择配置，也可以不配置：
|
||
|
||
|
||
|
||
## 认识 11 位 AI 团队成员（Agent）
|
||
|
||
OmO 内置了 11 个专门的 Agent，各司其职：
|
||
|
||
### 核心 Agent
|
||
|
||
| Agent | 角色 | 默认模型 | 什么时候用 |
|
||
| :------------- | :----------------- | :-------------------- | :--------------------------------- |
|
||
| **Sisyphus** | 主协调者、全能开发 | Claude Opus | 所有任务的入口，自动调度其他 Agent |
|
||
| **Prometheus** | 战略规划师 | Claude Opus / GPT-5.4 | 复杂任务的计划制定 |
|
||
| **Atlas** | 待办任务管理 | Kimi K2.5 | 跟踪多步骤任务进度 |
|
||
|
||
### 专业 Agent
|
||
|
||
| Agent | 角色 | 默认模型 | 擅长什么 |
|
||
| :------------- | :---------------- | :------------ | :------------------------------- |
|
||
| **Hephaestus** | 深度自主工作者 | GPT-5.3-codex | 长时间、高强度的独立编码任务 |
|
||
| **Oracle** | 架构顾问/调试专家 | GPT-5.4 | 系统设计、疑难 bug 定位 |
|
||
| **Momus** | 高精度审查员 | GPT-5.4 | 代码 review、输出验证 |
|
||
| **Metis** | 计划评审 | Claude Opus | 检查 Prometheus 的计划是否有遗漏 |
|
||
|
||
### 工具型 Agent（快速、低成本）
|
||
|
||
| Agent | 角色 | 默认模型 | 为什么用便宜模型 |
|
||
| :-------------------- | :------------- | :----------------------- | :------------------------------- |
|
||
| **Explore** | 代码库快速搜索 | MiniMax / Grok Code Fast | 搜索任务不需要高智能，速度更重要 |
|
||
| **Librarian** | 文档/代码检索 | MiniMax（免费） | 文档检索不需要深度推理 |
|
||
| **Multimodal Looker** | 截图/视觉分析 | Kimi K2.5 | Kimi 擅长多模态理解 |
|
||
|
||
> 💡 **新手提示**：你不需要手动选择 Agent。Sisyphus 会根据你的任务类型自动调度合适的 Agent 组合。
|
||
|
||
## 三种工作模式
|
||
|
||
### 模式一：ultrawork（最轻松）
|
||
|
||
在提示词里加 `ultrawork` 或 `ulw`，一切自动化：
|
||
|
||
```
|
||
ultrawork 帮我把这个 React 组件改成 TypeScript
|
||
```
|
||
|
||
适合：日常开发任务，希望 AI 全自动完成的场景。
|
||
|
||
### 模式二：Prometheus 计划模式（最精准）
|
||
|
||
按 **Tab 键** 进入 Prometheus 模式。AI 会先通过问答了解你的需求，生成详细执行计划，确认后再开始执行。
|
||
|
||
流程：
|
||
|
||
1. 按 `Tab` 切换到 Prometheus 模式
|
||
2. 描述你的需求，AI 会问你一些澄清问题
|
||
3. AI 生成执行计划，你确认
|
||
4. 输入 `/start-work` 开始执行
|
||
|
||
适合：复杂功能开发、架构重构等需要精确规划的场景。
|
||
|
||
### 模式三：普通对话（最灵活）
|
||
|
||
直接输入你的问题或需求，不加任何关键词：
|
||
|
||
```
|
||
解释一下 src/auth.ts 里的 JWT 验证逻辑
|
||
```
|
||
|
||
适合：问问题、代码解释、小修改等轻量任务。
|
||
|
||
|
||
|
||
## 配置文件详解
|
||
|
||
OmO 有两个配置文件，优先级不同：
|
||
|
||
- 项目级配置（优先级更高）：**.opencode/oh-my-opencode.jsonc**
|
||
- 用户级配置（全局默认）：**~/.config/opencode/oh-my-opencode.jsonc**
|
||
|
||
配置文件支持注释（JSONC 格式），也支持 JSON Schema 自动补全：
|
||
|
||
```json
|
||
{
|
||
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
|
||
|
||
"agents": {
|
||
// 主协调 Agent，官方建议用 Claude Opus 系列
|
||
"sisyphus": {
|
||
"model": "anthropic/claude-opus-4-6"
|
||
},
|
||
// 架构顾问，官方建议用 GPT 系列
|
||
"Hephaestus": {
|
||
"model": "openai/gpt-5.4",
|
||
"variant": "high"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **新手建议**：安装完成后先不要修改配置，默认设置已经很好。
|
||
|
||
## 常用命令
|
||
|
||
在对话界面内：
|
||
|
||
| 快捷键/命令 | 说明 |
|
||
| :------------------ | :--------------------------------- |
|
||
| `Tab` | 切换到 Prometheus 计划模式 |
|
||
| `/start-work` | 在 Prometheus 模式下开始执行计划 |
|
||
| `ultrawork` / `ulw` | 在提示词里加上，激活全功能并行模式 |
|
||
|