wenyongda 37bc43dd6b Update OpenCode migration guide and configuration details; change post date to June 13, 2026

2026-07-03 16:31:43 +08:00

15 KiB

Raw Blame History

title, date, tags

title	date	tags
OpenCode	2026-06-13 10:34:02

OpenCode 安装指南

Windows 安装方式

方式一：使用 npm 安装（推荐）

确保已安装 Node.js（建议版本 16 或更高）
打开 PowerShell 或命令提示符
运行以下命令进行全局安装：
```
npm i -g opencode-ai
```
安装完成后，可以通过以下命令验证安装：
```
opencode --version
```

方式二：使用 curl 安装（需要 WSL 或 Git Bash）

如果您使用的是 Windows Subsystem for Linux (WSL) 或 Git Bash，可以使用以下命令：

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

注意： 此方式需要在 Unix-like 环境中运行，Windows 原生的命令提示符或 PowerShell 不支持此命令。

其他操作系统安装方式

Linux/macOS

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

或使用 npm：

npm i -g opencode-ai

常见问题

PowerShell 中使用 curl 安装后命令不识别

问题描述： 在 PowerShell 中运行 curl -fsSL https://opencode.ai/install | bash 后，opencode 命令无法识别。

原因分析：

PowerShell 中的 curl 是 Invoke-WebRequest 的别名，不是真正的 curl
bash 命令在 PowerShell 中不可用（除非安装了 WSL 或 Git Bash）
即使安装成功，安装路径可能不在 Windows PATH 中

解决方案：

方案一：使用 npm 安装（推荐）

npm i -g opencode-ai

方案二：在 WSL 或 Git Bash 中安装

打开 WSL 或 Git Bash

运行安装命令：

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

如果仍然不识别，检查安装路径并添加到 PATH

方案三：手动添加 PATH

如果已安装但命令不识别：

找到安装位置（通常在 ~/.local/bin 或 /usr/local/bin）

将路径添加到 Windows PATH：

[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\path\to\opencode", "User")

重启 PowerShell

nvm 用户切换 Node.js 版本后 opencode 不可用

问题描述： 使用 nvm（Node Version Manager）管理 Node.js 版本时，切换版本后之前全局安装的 opencode 命令无法识别。

原因分析： nvm 为每个 Node.js 版本维护独立的全局包目录。当您切换 Node.js 版本时：

每个版本有自己独立的 node_modules 目录
之前版本安装的全局包在新版本中不可用
需要重新安装全局包

解决方案：

方案一：为当前版本重新安装（推荐）

# 切换到目标 Node.js 版本
nvm use 18

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

方案二：使用 nvm 的默认包迁移功能

# 设置默认 Node.js 版本
nvm alias default 18

# 重新安装全局包
npm i -g opencode-ai

方案三：使用 nvm 的 --default-packages 参数

在安装 Node.js 版本时指定默认包：

# 设置默认包列表
echo "opencode-ai" > ~/.nvm/default-packages

# 安装新版本时会自动安装默认包
nvm install 18

方案四：检查当前 Node.js 版本

# 查看当前使用的 Node.js 版本
node --version

# 查看 nvm 列表
nvm list

# 切回之前安装 opencode 的版本
nvm use <之前版本号>

最佳实践：

在切换版本后检查全局包：npm list -g --depth=0
为常用版本安装 opencode：nvm use <版本> && npm i -g opencode-ai
考虑使用 nvm alias default <版本> 设置默认版本

方案五：配置独立的全局包目录（一劳永逸）

将 npm 全局包目录设置到固定位置，不依赖于 nvm 管理的 Node.js 版本：

# 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，可以迁移到其他版本：

# 查看当前版本
nvm current

# 切换到目标版本
nvm use 18

# 将之前版本的全局包迁移到当前版本
nvm reinstall-packages <源版本号>

例如：nvm reinstall-packages 16.20.0 将 16.20.0 版本的全局包迁移到当前版本。

权限问题

如果在 Linux/macOS 上遇到权限错误，请使用 sudo：

sudo npm i -g opencode-ai

网络问题

如果下载速度慢，可以尝试使用镜像源：

npm config set registry https://registry.npmmirror.com
npm i -g opencode-ai

验证安装

安装完成后，运行以下命令验证：

opencode --version

如果显示版本号，则表示安装成功。

迁移 OpenCode 配置

当需要在新机器上恢复 OpenCode 配置时，可以使用以下方法迁移。

源机器打包

在源机器上打包 OpenCode 配置文件和目录：

Linux/macOS

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 配置

新机器恢复

在新机器上恢复配置：

# 解压配置文件到用户目录
tar -xzf opencode-migration.tar.gz -C ~/

# 进入 OpenCode 配置目录并安装依赖
cd ~/.config/opencode && npm install

迁移后验证

# 验证 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）

# 创建临时目录存放配置文件
$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）

# 解压配置文件
$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）

# 检查配置文件是否存在
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 相同的方式：

# 打包
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 会先通过问答了解你的需求，生成详细执行计划，确认后再开始执行。

流程：

按 Tab 切换到 Prometheus 模式
描述你的需求，AI 会问你一些澄清问题
AI 生成执行计划，你确认
输入 /start-work 开始执行

适合：复杂功能开发、架构重构等需要精确规划的场景。

模式三：普通对话（最灵活）

直接输入你的问题或需求，不加任何关键词：

解释一下 src/auth.ts 里的 JWT 验证逻辑

适合：问问题、代码解释、小修改等轻量任务。

配置文件详解

OmO 有两个配置文件，优先级不同：

项目级配置（优先级更高）：.opencode/oh-my-opencode.jsonc
用户级配置（全局默认）：~/.config/opencode/oh-my-opencode.jsonc

配置文件支持注释（JSONC 格式），也支持 JSON Schema 自动补全：

{
  "$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`	在提示词里加上，激活全功能并行模式

15 KiB Raw Blame History Unescape Escape

OpenCode 安装指南

Windows 安装方式

方式一：使用 npm 安装（推荐）

方式二：使用 curl 安装（需要 WSL 或 Git Bash）

其他操作系统安装方式

Linux/macOS

常见问题

PowerShell 中使用 curl 安装后命令不识别

方案一：使用 npm 安装（推荐）

方案二：在 WSL 或 Git Bash 中安装

方案三：手动添加 PATH

nvm 用户切换 Node.js 版本后 opencode 不可用

方案一：为当前版本重新安装（推荐）

方案二：使用 nvm 的默认包迁移功能

方案三：使用 nvm 的 --default-packages 参数

方案四：检查当前 Node.js 版本

方案五：配置独立的全局包目录（一劳永逸）

方案六：使用 nvm 的 reinstall-packages 迁移包

权限问题

网络问题

验证安装

迁移 OpenCode 配置

源机器打包

Linux/macOS

新机器恢复

迁移后验证

注意事项

Windows 系统迁移

源机器打包（PowerShell）

新机器恢复（PowerShell）

Windows 配置文件路径

验证迁移（PowerShell）

使用 tar 命令（Windows 10+）

注意事项

OpenCode 插件

oh-my-openagent 使用教程

安装

认识 11 位 AI 团队成员（Agent）

核心 Agent

专业 Agent

工具型 Agent（快速、低成本）

三种工作模式

模式一：ultrawork（最轻松）

模式二：Prometheus 计划模式（最精准）

模式三：普通对话（最灵活）

配置文件详解

常用命令

15 KiB

Raw Blame History