菜单
文章 Tools

Windows + WSL + fnm + opencode-ai 完整安装与规范教程

UP

UP

• 阅读本文需 3 分钟

你的电脑分三层：

Windows（外层）
└── WSL Linux（开发环境）
    ├── 项目
    ├── 工具
    └── 启动脚本

很多人乱，是因为：

  • 项目和工具混在一起
  • npm -g 全局污染
  • Node 版本混乱
  • 找不到可执行文件在哪里

我们今天解决所有问题。

第一步：安装 WSL

PowerShell（管理员）：

wsl --install

重启。

选择 Ubuntu 或 Debian。

进入后看到：

host@DESKTOP:~$

第二步：建立标准目录结构

进入：

cd ~

创建：

mkdir workspace
mkdir tools
mkdir scripts
mkdir env

结构变成：

/home/host
├── workspace   （项目）
├── tools       （AI工具）
├── scripts     （快捷启动命令）
└── env         （Python虚拟环境）

记住一句话：

工具永远放 tools
项目永远放 workspace

第三步：使用 fnm 管理 Node

安装：

curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc

安装 Node LTS：

fnm install --lts
fnm use lts-latest
fnm default lts-latest

确认：

node -v
npm -v

第四步：正确安装 opencode-ai

进入工具目录：

cd ~/tools
mkdir opencode
cd opencode

初始化：

npm init -y

安装：

npm install opencode-ai

安装完成后，真实结构是：

/home/host/tools/opencode
└── node_modules
    └── opencode-ai
        └── bin
            └── opencode   ← 真正的可执行文件

完整路径：

/home/host/tools/opencode/node_modules/opencode-ai/bin/opencode

这说明：

👉 你是局部安装
👉 没污染系统
👉 很干净

第五步：让 opencode 可以直接使用

我们不会每次都打长路径。

我们创建“启动脚本”。

创建快捷命令

nano ~/scripts/opencode

写入：

#!/bin/bash
/home/host/tools/opencode/node_modules/opencode-ai/bin/opencode "$@"

保存。

赋予执行权限：

chmod +x ~/scripts/opencode

把 scripts 加入 PATH：

echo 'export PATH="$HOME/scripts:$PATH"' >> ~/.bashrc
source ~/.bashrc

现在你可以直接运行：

opencode

它会自动调用：

node_modules/opencode-ai/bin/opencode

为什么不用 npm -g？

如果你用：

npm install -g opencode-ai

文件会跑到：

~/.fnm/.../lib/node_modules/

问题是：

  • 升级 Node 会丢失
  • 多 Node 版本会冲突
  • 卸载难管理
  • 全局污染

局部安装更干净。

多个 AI 工具怎么管理？

例如：

~/tools/
├── opencode
├── claude-code
├── gemini-cli

每个工具：

  • 单独 npm init
  • 单独 npm install
  • 单独启动脚本

这样：

  • 升级互不影响
  • 删除一个不影响其他
  • 非常清晰

API Key 专业管理方式

创建目录：

mkdir -p ~/.config/ai-tools

创建文件：

nano ~/.config/ai-tools/keys.env

写：

export OPENAI_API_KEY=你的key
export ANTHROPIC_API_KEY=你的key

在 ~/scripts/opencode 顶部加入：

source ~/.config/ai-tools/keys.env

这样：

  • 不写死在代码里
  • 不泄露
  • 不混乱

🐍 Python 工具怎么办？

永远不要：

pip install xxx

要：

python3 -m venv ~/env/toolname
source ~/env/toolname/bin/activate
pip install xxx

如果你之前乱装过怎么办？

查看全局：

npm list -g --depth=0

卸载：

npm uninstall -g 包名

确认：

which opencode

如果没有输出，说明干净。

最终标准结构

/home/host
├── workspace
│
├── tools
│   ├── opencode
│   ├── claude-code
│   └── gemini-cli
│
├── scripts
│   ├── opencode
│   ├── claude
│   └── gemini
│
└── env

最核心思想

不要问：

可执行文件在哪里？

你只需要知道：

tools 放工具
scripts 放入口

你永远不需要去管：

node_modules/opencode-ai/bin/opencode

那是 npm 的内部结构。

分享