Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Windows 用户:从零开始用 WSL 运行 Avibe
这篇文档是写给 完全没有用过 WSL 的 Windows 用户的。
如果你看到“推荐用 WSL”,但完全不知道它去哪里安装、怎么打开、要在哪个窗口里执行命令,就按这篇文档一步一步做。
先说结论
如果你在 Windows 上使用 Avibe,我更推荐下面这套方式:
Windows:浏览器、Slack、Discord、Telegram、微信、飞书WSL:Avibe、Claude Code / Codex / OpenCode、你的代码仓库
简单理解就是:
- 你平时还是在 Windows 里点浏览器、看聊天工具
- 但真正执行命令和跑 Agent 的地方,不在 PowerShell,也不在 CMD,而是在一个 Linux 终端窗口里
这个 Linux 终端窗口,就是 WSL。
什么是 WSL
WSL 的全称是 Windows Subsystem for Linux。
你可以把它理解成:
- 你的电脑还是 Windows
- 但 Windows 里面多开了一个 Linux 命令行环境
- 你可以在这个 Linux 环境里运行很多更适合开发者工具的命令
对 Avibe 这种要调用 Python、Node、Agent CLI 的程序来说,WSL 通常比原生 Windows 更稳。
你会用到两个窗口
这一步非常重要,很多人第一次会搞混。
窗口 1:PowerShell
PowerShell 只在最开始安装 WSL 时用一下。
你可以把它理解成:
- 用来“安装 WSL 本身”的 Windows 终端
窗口 2:Ubuntu 终端
Ubuntu 终端才是后面真正运行 Avibe 的地方。
你可以把它理解成:
- 用来“安装和运行 Avibe”的 Linux 终端
后面看到类似下面这些命令:
curl ...
vibe
which codex
都应该在 Ubuntu 终端 里执行,不是在 PowerShell 里执行。
第一步:安装 WSL
1. 打开 PowerShell
在 Windows 里:
- 点开始菜单
- 搜索
PowerShell - 找到
Windows PowerShell或PowerShell - 右键
- 选择
以管理员身份运行
2. 在 PowerShell 里执行安装命令
输入:
wsl --install
这条命令的作用是:
- 安装 WSL
- 安装默认 Linux 发行版(通常是 Ubuntu)
如果系统提示你重启,就重启电脑。
3. 重启后再次进入 Windows
安装完成后,你的开始菜单里通常会出现:
Ubuntu
如果没有看到,也可以搜索:
UbuntuWindows Terminal
第二步:第一次启动 Ubuntu
1. 打开 Ubuntu
点开始菜单,搜索并打开:
Ubuntu
第一次打开时,系统会做一些初始化,这一步可能要等几十秒到几分钟。
2. 创建 Linux 用户名和密码
初始化完成后,Ubuntu 会提示你创建:
- 一个 Linux 用户名
- 一个 Linux 密码
这里的用户名和密码是 WSL 里的 Linux 账号,不是你的 Windows 账号。
比如它可能让你输入:
Enter new UNIX username:
Enter new UNIX password:
设好之后,以后这个 Ubuntu 终端就是你的 WSL 工作环境。
第三步:确认你已经进入 WSL 终端
当你看到类似下面这样的提示符时,通常就说明你已经在 Ubuntu 里了:
yourname@DESKTOP-XXXX:~$
注意这里通常会有:
- 你的 Linux 用户名
- 一个波浪号
~ - 一个美元符号
$
这表示你现在在 Linux 终端里。
从这一步开始,后面的命令都在这个窗口里执行。
第四步:先更新 Ubuntu 里的基础工具
在 Ubuntu 终端里执行:
sudo apt update
sudo apt install -y curl git
如果系统要求输入密码,就输入你刚才创建的 Linux 密码。
第五步:准备一个工作目录
推荐把代码放在 WSL 自己的 Linux 文件系统里,而不是放在 Windows 的 C: 盘映射路径里。
在 Ubuntu 终端里执行:
mkdir -p ~/work
cd ~/work
推荐使用:
/home/<你的 Linux 用户名>/work
不建议长期把项目放在:
/mnt/c/Users/...
因为那样通常更慢,也更容易遇到权限和路径兼容问题。
第六步:安装 Avibe
现在你已经在正确的地方了。
就在 Ubuntu 终端 里执行:
curl -fsSL https://avibe.bot/install.sh | bash
开源脚本,源码在 GitHub 上;该短链只是到这个文件的 307 重定向。
安装完成后,继续在同一个 Ubuntu 终端里执行:
vibe
再次强调:
- 这条命令在
Ubuntu 终端里执行 - 不是在 PowerShell 里执行
- 也不是在 CMD 里执行
第七步:在 Windows 浏览器里打开 Web UI
Avibe 启动后,Web UI 默认地址是:
http://127.0.0.1:5123
这时候你可以在 Windows 的浏览器 里打开这个地址,比如:
- Chrome
- Edge
- Firefox
直接访问:
http://127.0.0.1:5123
如果浏览器没有自动弹出来,手动打开这个地址就行。
第八步:安装 Agent CLI
如果你要用 Claude Code、Codex 或 OpenCode,这些 CLI 也应该安装在 Ubuntu 终端 里。
不要只装在 Windows 里。
因为:
- Avibe 跑在 WSL 里
- 它只会调用 WSL 里能找到的命令
安装完成后,你可以在 Ubuntu 终端里确认:
which claude
which codex
which opencode
如果能看到类似下面的输出,就说明这个命令已经能在 WSL 里被找到:
/home/yourname/.local/bin/codex
第九步:设置默认工作目录
在 Avibe 的 Web UI 里,把默认工作目录设置成 WSL 路径,例如:
/home/yourname/work
不要优先设置成:
C:\Users\...
也不要优先设置成:
/mnt/c/Users/...
如果你一定要访问 Windows 文件,也可以临时用 /mnt/c/...,但不建议作为长期默认目录。
一个最容易理解的使用例子
你每天可以这样使用:
1. 打开 Ubuntu
开始菜单 -> 搜索 Ubuntu -> 打开
2. 进入项目目录
在 Ubuntu 终端里:
cd ~/work/your-project
3. 启动 Avibe
在 Ubuntu 终端里:
vibe
4. 打开浏览器
在 Windows 浏览器里访问:
http://127.0.0.1:5123
5. 在聊天工具里使用
之后你就在 Slack、Discord、Telegram、微信、飞书里和 Agent 交互。
如何再次打开 WSL
以后每次想继续使用,不需要重新安装。
你只需要:
- 打开开始菜单
- 搜索
Ubuntu - 打开 Ubuntu
- 在里面执行:
cd ~/work/你的项目
vibe
常见问题
1. 我应该在哪个窗口里执行 vibe?
答:在 Ubuntu 终端 里,不是在 PowerShell 里。
2. 我应该在哪个窗口里执行 curl ... | bash?
答:在 Ubuntu 终端 里,不是在 PowerShell 里。
3. PowerShell 还要不要继续用?
只在最开始安装 WSL 时需要。
安装完成后,日常使用 Avibe 基本都在 Ubuntu 终端里。
4. 浏览器打不开 127.0.0.1:5123 怎么办?
先确认 Ubuntu 终端里 vibe 还在运行。
如果 vibe 已经退出,浏览器当然打不开。
你可以先在 Ubuntu 终端里看一下:
vibe status
5. Web UI 里安装 Agent 失败怎么办?
如果你是在 Windows 浏览器里操作,而 Avibe 跑在 WSL 里,有时本地安全校验可能让某些安装按钮失败。
这时不要卡在按钮里,直接回到 Ubuntu 终端 手动安装对应的 CLI,然后回到 Web UI 填路径或重新检测即可。
6. 我必须懂 Linux 才能用吗?
不用。
你只需要会做这几件事:
- 打开 Ubuntu
cd进入目录- 运行
vibe - 在浏览器里打开
http://127.0.0.1:5123
这就够开始用了。
快速检查清单
如果下面这些都成立,说明你的 WSL 方案已经跑通了:
- 你能在开始菜单里打开
Ubuntu - Ubuntu 打开后能看到类似
yourname@DESKTOP-XXXX:~$ - 你能在 Ubuntu 终端里运行
vibe - 你能在 Windows 浏览器里打开
http://127.0.0.1:5123 which codex/which claude/which opencode能在 Ubuntu 里找到对应命令
官方参考
如果你想看微软官方文档,可以参考:
- WSL 安装:https://learn.microsoft.com/windows/wsl/install
- WSL 基础命令:https://learn.microsoft.com/windows/wsl/basic-commands
- WSL 开发环境说明:https://learn.microsoft.com/windows/wsl/setup/environment
一句话建议
如果你是 Windows 用户,而且不确定原生 Windows 能不能稳定跑所有 Agent CLI,那么最稳的方式就是:
- 先在 Windows 里安装 WSL
- 再打开 Ubuntu
- 在 Ubuntu 终端里安装并运行 Avibe
- 在 Windows 浏览器里访问
http://127.0.0.1:5123
这样通常最省心。