Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

8.5 KB
Raw Blame

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 里:

  1. 点开始菜单
  2. 搜索 PowerShell
  3. 找到 Windows PowerShell 或 PowerShell
  4. 右键
  5. 选择 以管理员身份运行

2. 在 PowerShell 里执行安装命令

输入:

wsl --install

这条命令的作用是:

  • 安装 WSL
  • 安装默认 Linux 发行版(通常是 Ubuntu)

如果系统提示你重启,就重启电脑。

3. 重启后再次进入 Windows

安装完成后,你的开始菜单里通常会出现:

  • Ubuntu

如果没有看到,也可以搜索:

  • Ubuntu
  • Windows 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

以后每次想继续使用,不需要重新安装。

你只需要:

  1. 打开开始菜单
  2. 搜索 Ubuntu
  3. 打开 Ubuntu
  4. 在里面执行:
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 里找到对应命令

官方参考

如果你想看微软官方文档,可以参考:

一句话建议

如果你是 Windows 用户,而且不确定原生 Windows 能不能稳定跑所有 Agent CLI,那么最稳的方式就是:

  • 先在 Windows 里安装 WSL
  • 再打开 Ubuntu
  • 在 Ubuntu 终端里安装并运行 Avibe
  • 在 Windows 浏览器里访问 http://127.0.0.1:5123

这样通常最省心。