一、升级 Node.js（必须先做）
OpenCode 要求 Node.js 18+，你当前的 v10.24.0 跑不起来 。
- 安装 nvm（国内镜像，绕过 GitHub）
创建 nvm 目录并手动下载核心文件（绕过 git clone）
mkdir -p ~/.nvm && cd ~/.nvm
wget https://gitee.com/mirrors/nvm/raw/v0.39.7/nvm.sh -O nvm.sh
wget https://gitee.com/mirrors/nvm/raw/v0.39.7/nvm-exec -O nvm-exec
wget https://gitee.com/mirrors/nvm/raw/v0.39.7/bash_completion -O bash_completion
chmod +x nvm-exec
配置 shell
cat >> ~/.bashrc << 'EOF'
export NVM_DIR=" H O M E / . n v m " − s " HOME/.nvm" \[ -s " HOME/.nvm"\[−s"NVM_DIR/nvm.sh" && . " N V M D I R / n v m . s h " − s " NVM_DIR/nvm.sh" \[ -s " NVMDIR/nvm.sh"\[−s"NVM_DIR/bash_completion" && . "$NVM_DIR/bash_completion"
EOF
source ~/.bashrc
- 安装 Node.js 18（国内镜像）
关键：指向国内镜像，否则 nvm install 会卡死
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.bashrc
source ~/.bashrc
安装 Node 18
nvm install 18
nvm alias default 18
验证
node -v # v18.x.x
npm -v # 9.x.x 或 10.x.x
💡 如果 nvm install 18 还是卡，用离线方案：从 https://npmmirror.com/mirrors/node/v18.20.4/node-v18.20.4-linux-x64.tar.xz 手动下载，解压到 ~/.nvm/versions/node/v18.20.4/。
二、安装 OpenCode
方式一：npm 全局安装（推荐）
设置 npm 国内镜像
npm config set registry https://registry.npmmirror.com
全局安装
npm install -g opencode-ai
验证
opencode --version
方式二：一键脚本（需要能访问 opencode.ai）
curl -fsSL https://opencode.ai/install | bash
启动 OpenCode
在项目目录启动终端 TUI
opencode
或启动 Web 界面（远程/容器环境有用）
opencode web --hostname 0.0.0.0 --port 4242
三、添加自定义 Skill（核心）
OpenCode 的 Skill 是放在特定目录下的 SKILL.md 文件，OpenCode 会自动发现并加载 。
- Skill 的存放位置
OpenCode 会搜索以下目录 ：
作用域
路径
项目级（仅当前项目）
<项目根>/.opencode/skills/<skill名>/SKILL.md
全局（所有项目）
~/.config/opencode/skills/<skill名>/SKILL.md
Claude 兼容（项目级）
<项目根>/.claude/skills/<skill名>/SKILL.md
Claude 兼容（全局）
~/.claude/skills/<skill名>/SKILL.md
💡 建议：个人常用 skill 放全局 ~/.config/opencode/skills/；项目专属 skill 放项目内的 .opencode/skills/
- SKILL.md 的格式规范
每个 Skill 是一个目录，里面至少有一个 SKILL.md 文件 ：
skill-name/
├── SKILL.md # 必需：核心定义文件
├── scripts/ # 可选：可执行脚本（Python/Bash）
├── references/ # 可选：参考文档
└── assets/ # 可选：模板、图片等资源
SKILL.md 的开头必须是 YAML frontmatter，目前 OpenCode 仅识别这些字段 ：
name: skill-name # 必填，1-64 字符，小写字母数字+连字符，必须和目录名一致
description: 描述文本 # 必填，1-1024 字符，要写清楚"做什么、什么时候用、举几个例子"
license: MIT # 可选
compatibility: opencode # 可选
metadata: # 可选
key: value
name 的命名规则（正则 [1](#1)+(-a-z0-9+)*$）：
只能小写字母、数字、连字符
不能以 - 开头或结尾
不能有连续的 --
必须与包含 SKILL.md 的目录名一致
- a-z0-9 ↩︎