Windows 用户安装指南

Windows 用户需要通过 WSL (Windows Subsystem for Linux) 来使用 OpenClacky。本文将引导你完成 WSL 安装和 OpenClacky 的配置。

前置要求

  • Windows 10 版本 2004 及更高版本（内部版本 19041 及更高版本）或 Windows 11
  • 管理员权限

第一步：安装 WSL

打开 PowerShell 或 Windows 命令提示符（以管理员身份运行），输入以下命令：

wsl --install

这条命令会自动：
- 启用 WSL 功能
- 安装 Ubuntu 发行版（默认）
- 设置 WSL 2 作为默认版本

安装完成后，重启电脑。

国内用户安装方法

如果上述命令因网络问题无法完成安装，可以使用以下方法：

步骤一：安装 WSL 内核

打开 PowerShell 或 Windows 命令提示符（以管理员身份运行），输入以下命令：

开启 WSL 核心组件：

dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

开启虚拟机平台：

dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

完成后重启电脑。

重启后，在浏览器输入以下链接下载 WSL 内核：

https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

下载完成后双击运行并完成安装。

⚠️ 注意：安装若遇到报错 "This update only applies to machines with the Windows Subsystem for Linux"，则重新执行一次步骤一并重启电脑。

安装完成后打开 PowerShell 或 Windows 命令提示符，输入：

wsl --status

若弹出 WSL 内核信息，则可进行下一步骤。

步骤二：下载 Ubuntu 镜像

将以下链接粘贴到浏览器，下载 Ubuntu 镜像（文件较大，约 350MB，请耐心等待）：

https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/wsl/jammy/20250318/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz

下载完成后，镜像默认存放在 Windows 下载路径。若自定义过浏览器的下载文件夹，请找到下载好的镜像文件，移动到下载文件夹，方便查找路径。

打开 PowerShell 或 Windows 命令提示符（以管理员身份运行），按顺序输入以下命令：

cd .\Downloads\

然后输入：

pwd

获取到路径后复制记录下来，接着输入：

wsl --import Ubuntu "C:\WSL\Ubuntu" "<记录的路径>\ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz"

⚠️ 重要：请不要直接粘贴使用这条命令，务必将 <记录的路径> 替换成通过 pwd 获取的路径！

执行完成后输入：

wsl -l -v

验证是否存在 Ubuntu。

第二步：首次启动 WSL

重启后，从开始菜单打开"Ubuntu"应用。首次启动时会提示你：

  1. 等待安装完成（可能需要几分钟）
  2. 创建 Linux 用户名（可以和 Windows 用户名不同）
  3. 设置密码（输入时不会显示，这是正常的）

完成后，你就进入了 Linux 终端环境。

如果开始菜单没有 Ubuntu 应用

若开始菜单无“Ubuntu”应用，可打开 PowerShell 或 Windows 命令提示符，输入：

wsl

即可进入 Ubuntu 系统。

建议：使用 Windows 终端

PowerShell 和 Windows 命令提示符对 OpenClacky 的支持稍差，建议下载 Microsoft 最新的 Windows 终端，复制到浏览器下载：

https://aka.ms/terminal

安装完成后打开 Windows 终端，在标签页点击下箭头图标，选择 Ubuntu 即可。

💡 提示：建议在 Windows 终端的设置中，将“默认终端应用程序”修改为“Windows 终端”。

第三步：安装 OpenClacky

在 WSL 终端中，粘贴并运行创作者给你的安装命令。命令格式如下：

/bin/bash -c "$(curl -sSL https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.sh)" -- --brand-name="JohnAI" --command="johncli"

💡 提示：在 WSL 终端中，右键点击即可粘贴。

脚本会自动完成客户端的安装和品牌配置。

国内用户安装方法

由于网络环境差异，需要先将一些下载源配置为国内镜像源，避免因网络环境导致的下载失败。

1. 配置清华 apt 镜像源

在 Ubuntu 内输入：

sudo sed -i 's|http://archive.ubuntu.com/|https://mirrors.tuna.tsinghua.edu.cn/|g' /etc/apt/sources.list

然后输入：

sudo apt update

⚠️ 注意：使用 sudo 命令可能会需要输入密码，此处需要输入的密码为上一步设置的 Linux（Ubuntu）密码。

2. 安装基础依赖和 Ruby

sudo apt install -y curl bash ruby ruby-dev

3. 验证 Ruby 安装

依次输入以下命令，检查是否有版本号输出：

ruby -v

然后输入：

gem -v

4. 替换 gem 源为国内镜像源

依次在 Ubuntu 输入以下命令：

添加国内 gem 下载源：

gem sources --add https://gems.ruby-china.com/

移除默认 gem 下载源：

gem sources --remove https://rubygems.org/

检查当前 gem 下载源地址：

gem sources -l

若显示的 URL 为 https://gems.ruby-china.com/ 则替换成功。

5. 安装 OpenClacky

方案一：使用 gem 安装

sudo gem install openclacky

方案二：使用 curl 命令安装

curl -sSL https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.sh | bash

⚠️ 注意：以上方案二选一即可，请勿全部执行，导致重复安装。

6. 验证

在 Ubuntu 输入：

openclacky

若能正常打开即为安装成功。

第四步：激活序列号

安装完成后，运行创作者指定的命令（如 johncli）启动客户端。

首次启动会提示输入序列号。序列号由创作者提供，通常来自：

  • 购买的付费产品附带的激活码
  • 创作者社群中发放的专属码
  • 创作者的销售页面

输入序列号后即可开始使用预装的 Skill。

若您并非通过创作者安装命令安装 OpenClacky

则需要手动进入 WebUI 激活。

1. 启动 OpenClacky 服务

新建一个 Ubuntu 终端：
- 使用 Windows 终端的用户可以在标签页上直接添加
- 非 Windows 终端则需要打开一个新的 PowerShell 或 Windows 命令提示符，通过 wsl 命令进入 Ubuntu 系统

在新的 Ubuntu 终端输入：

openclacky server

当您看到类似以下信息时，代表 WebUI 启动成功：

xiangzi@LAPTOP-HH0GO490:~$ openclacky server

🌐 Clacky Web UI running at http://127.0.0.1:7070

   Version: 0.8.7

   Press Ctrl-C to stop.

   ⏰ Scheduler started (2 schedule(s) loaded)

2. 访问 WebUI 页面

openclacky server 启动成功后，在浏览器输入：

http://127.0.0.1:7070

或者：

localhost:7070

即可进入 OpenClacky WebUI 页面。

3. 激活序列号

  1. 复制您的激活码
  2. 在 WebUI 页面中左下角的 "Settings" 中，下滑找到 "Brand & License"
  3. 粘贴您的激活码激活
  4. 激活成功后需要手动按 F5 刷新页面
  5. 当 logo 从 "clacky" 变更为创作者品牌 logo 时，激活完成

日常使用

之后每次想使用 OpenClacky 时：

通过创作者安装命令安装的用户：

  1. 从开始菜单打开"Ubuntu"应用
  2. 在终端中运行创作者的命令（如 johncli）
  3. 开始工作

非创作者安装命令安装的用户：

打开 Ubuntu 终端（Windows 终端、PowerShell 或命令提示符输入 wsl）

  • 如您偏好在 WebUI 使用，运行命令：openclacky server

    在浏览器访问：http://127.0.0.1:7070 或 localhost:7070

  • 如您偏好在终端使用，运行命令：openclacky 即可开始使用

Windows 用户常见问题

Q: 安装 WSL 时提示"无法安装"？

A: 确保你以管理员身份运行 PowerShell，并且 Windows 版本符合要求（Win10 2004+ 或 Win11）。

Q: PowerShell 或 CMD 命令提示符乱码怎么办？

A: 在终端标题栏右键 → 属性 → 字体，选择支持中文的字体如"新宋体"或"Microsoft YaHei Mono"。如果修改字体仍无法解决乱码问题，请参考 Windows CMD 中文乱码解决方法 排除故障。

Q: 可以在 Windows 文件浏览器中访问 WSL 文件吗？

A: 可以！在文件浏览器地址栏输入 \\wsl$\Ubuntu 即可访问 WSL 中的文件。

Q: OpenClacky 可以访问 Windows 中的文件吗？

A: 可以。在 WSL 中，Windows 的 C 盘映射到 /mnt/c，D 盘映射到 /mnt/d，以此类推。

Q: C 盘空间不足导致 WSL 安装失败怎么办？

A: WSL 默认安装在 C 盘。如果 C 盘空间不足，建议通过以下方式释放或扩容 C 盘：

方法一：使用磁盘清理工具
1. 在开始菜单搜索"磁盘清理"并打开
2. 选择 C 盘，点击"确定"
3. 勾选"临时文件"、"下载"、"回收站"等项目，点击"清理系统文件"
4. 勾选"以前的 Windows 安装"（如有）可释放大量空间
5. 点击"确定"开始清理

方法二：扩容 C 盘
1. 右键点击"此电脑" → "管理" → "磁盘管理"
2. 选择相邻的其他盘符（如 D 盘），右键选择"压缩卷"
3. 输入要压缩的空间大小（如 20GB = 20480MB），点击"压缩"
4. 压缩完成后会出现"未分配"空间
5. 右键点击 C 盘，选择"扩展卷"，按向导将未分配空间合并到 C 盘

注意：扩容前请备份重要数据，且 C 盘必须与未分配空间相邻才能直接扩展。

Q: 看不懂安装文档，怎么安装 OpenClacky？

A: 您可以使用支持 MCP 协议的 AI Agent（如 MiniMax Agent、Claude Desktop 等）作为安装助手。直接对 Agent 说："请加载 https://www.openclacky.com/docs/openclackywin 这个在线 Skill，然后帮我安装 OpenClacky"。Agent 会自动读取安装步骤并逐步引导您完成安装。

Q: 序列号在哪里找？

A: 联系给你分享安装命令的创作者，或查看购买记录中的激活码。

下一步：如何使用 Skill →

为什么选 OpenClacky？