安装

目录

• 概览
• 前置要求
• 步骤 1：下载并运行安装脚本
• 步骤 2：GUI 设置向导（浏览器）
• 安装后：添加技能与软件包
• 各平台说明
  • Windows（WSL2）
• 安装脚本做了什么
  • 安装脚本写入的配置文件
  • 网络镜像与超时配置
• 卸载

概览

AcaClaw 安装分为两步：

步骤 1 需要终端，因为要安装系统级组件（Node 包、Conda 环境、CLI 工具）。这是唯一需要终端的一步。

步骤 2 在安装结束后自动在浏览器中打开。GUI 向导处理所有交互选择 — 无终端菜单、无需手写配置。

AcaClaw 不单独运行桌面 GUI 程序。它在自己的网关端口提供浏览器界面（http://localhost:2090）。OpenClaw 自带管理后台仍在默认网关运行（http://localhost:18789）。两个网关、两个端口、两套前端。

安装完成后，技能、学科包、配置与备份均可通过浏览器管理。详见 Web 界面。

平台支持

前置要求

仅在使用 最高安全模式（代码均在容器中运行）时需要 Docker。

若无 Node.js，请从 nodejs.org 安装。

步骤 1：下载并运行安装脚本

在终端执行：

curl -fsSL https://acaclaw.com/install.sh | bash

或先下载再审阅：

curl -fsSL https://acaclaw.com/install.sh -o install.sh
less install.sh
bash install.sh

脚本会自动安装依赖，结束时启动网关并在浏览器打开设置向导。

步骤 2：GUI 设置向导（浏览器）

安装完成后，浏览器会打开 http://localhost:2090/ 进入 AcaClaw 设置向导。

为什么使用 Web 应用向导而不是原生二进制文件？

由于隔离区（Quarantine）和智能屏幕保护等机制，终端安装脚本很难在所有操作系统上安全可靠地启动原生 GUI 应用程序。

作为替代，安装程序会尝试使用你现有的 Chrome 或 Edge 浏览器，将设置向导作为一个独立的应用窗口（即“Dock 应用”，没有浏览器标签页或地址栏）启动。如果找不到支持的浏览器，它会优雅地回退到打开一个标准的浏览器标签页。

这提供了一种原生应用般的体验，同时完全在本地运行且受操作系统信任。

向导页面

第 1 屏 — 学科：选择主要研究领域，决定 Conda 中预装哪些科学包。

第 2 屏 — AI 服务商：选择 Anthropic / OpenAI / Google AI / OpenClaw Web，填写 API 密钥并测试连接，选择模型。

第 3 屏 — 工作区位置：默认 ~/AcaClaw/，可更换目录并预览将创建的目录结构。

第 4 屏 — 安全级别：标准（推荐）或最高（需 Docker）。

第 5 屏 — 完成：汇总选项，点击完成；后台为所选学科创建 Conda 环境。

完成后进入 AcaClaw 控制台，安装结束。

安装后：添加技能与软件包

初始设置之后的操作均在浏览器中完成。

安装新技能

浏览器 Skills 标签 → ClawHub → 浏览或搜索 → Install。网关通过 WebSocket 调用 skills.install 并显示进度。

添加新学科

Environment 标签 → Add Discipline → 选择化学、生物等。网关调用 acaclaw.env.install，后台执行 conda env create，界面显示进度条。

安装单个软件包

Environment 标签 → Install Package → 输入包名，通过网关在活动环境中执行 conda install。

底层机制

浏览器不直接执行 shell。它向网关发 WebSocket 消息，由网关启动实际进程（clawhub install、conda install、conda env create），进度与错误通过 WebSocket 回传。

各平台说明

Linux

curl -fsSL https://acaclaw.com/install.sh | bash

• 需 Node.js 22+
• 通过 xdg-open http://localhost:2090/ 打开向导
• 无显示服务器（无头/SSH）时脚本会打印需手动访问的 URL
• 桌面集成：安装 .desktop 文件，可在启动器与 Dock 中固定 AcaClaw

macOS

curl -fsSL https://acaclaw.com/install.sh | bash

• 支持 Intel 与 Apple Silicon
• 需 Xcode Command Line Tools（脚本可提示安装）
• 通过 open http://localhost:2090/ 打开向导
• 桌面集成：~/Applications/AcaClaw.app、桌面别名、书签三层保障

Windows（WSL2）

# 在 WSL2 终端中执行
curl -fsSL https://acaclaw.com/install.sh | bash

安装脚本自动检测 WSL2（通过 WSL_DISTRO_NAME 或 /proc/version），走标准 Linux 安装流程，并附加四项 WSL2 专属操作：

WSL2 与原生 Linux 的区别

1. 通过 Windows 浏览器实现独立应用窗口

WSL2 没有原生显示服务器。安装脚本不尝试打开 Linux 浏览器（那需要 WSLg 或 X 服务器），而是直接启动 Windows 侧浏览器：

# install.sh 在 PLATFORM=wsl2 时的检测逻辑
cmd.exe /c start "" "http://localhost:2090/"

WSL2 自动将 localhost 端口转发到 Windows，因此 http://localhost:2090/ 会在用户的默认 Windows 浏览器（通常是 Edge 或 Chrome）中打开 AcaClaw 界面。

为实现独立应用窗口体验（无地址栏、无浏览器标签页），安装脚本尝试在 Windows 侧使用 Chromium --app 模式：

# 优先尝试 Edge（Windows 10/11 预装）
"/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" \
  --app="http://localhost:2090/" --no-first-run --disable-fre &

# 回退：Chrome
"/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" \
  --app="http://localhost:2090/" --no-first-run &

# 最终回退：普通浏览器标签页
cmd.exe /c start "" "http://localhost:2090/"

这为用户提供了与 macOS（WKWebView）和原生 Linux（PWA）相同的无框应用窗口体验，但使用的是 Windows Edge/Chrome。

2. 设置向导在 Windows 侧打开

设置向导（API 密钥输入、学科选择、安全级别）在 Windows 浏览器中打开，而不在 WSL2 内部打开。原因：

• 用户从 Windows 密码管理器 / 浏览器会话中复制粘贴 API 密钥
• Windows 是主要桌面环境；WSL2 是计算后端
• 不依赖 WSLg 或 X11 转发

安装脚本检测 WSL2 后调用 cmd.exe /c start 而非 xdg-open：

case "$PLATFORM" in
  wsl2)
    # 在 Windows 浏览器中打开，而非 WSL2 Linux 浏览器
    cmd.exe /c start "" "$SETUP_URL" 2>/dev/null || true
    ;;
esac

3. Windows 桌面上的工作区快捷方式

在 WSL2 内创建 ~/AcaClaw/ 后，安装脚本在用户的 Windows 桌面上创建一个快捷方式，指向 WSL2 工作区文件夹：

Windows 桌面/
  AcaClaw Workspace.lnk  →  \\wsl$\Ubuntu\home\user\AcaClaw\

用户可以从 Windows 文件资源管理器直接浏览研究文件，无需手动输入 \\wsl$\ 路径。通过 PowerShell 创建：

$desktop = [Environment]::GetFolderPath('Desktop')
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut("$desktop\AcaClaw Workspace.lnk")
$shortcut.TargetPath = "\\wsl$\$distro\home\$user\AcaClaw"
$shortcut.Description = "AcaClaw Research Workspace (WSL2)"
$shortcut.Save()

4. Windows 桌面上的应用快捷方式

第二个 .lnk 快捷方式创建在 Windows 桌面上，用于启动 AcaClaw：

Windows 桌面/
  AcaClaw.lnk  →  wsl.exe -d Ubuntu -- bash ~/.acaclaw/start.sh

双击此快捷方式：

1. 在 WSL2 内启动网关（如果尚未运行）
2. 在 Windows 浏览器中以独立应用窗口打开 http://localhost:2090/
3. 无终端窗口保留（快捷方式以最小化方式运行）

通过 PowerShell 创建：

$shortcut.TargetPath = "wsl.exe"
$shortcut.Arguments = "-d $distro -- bash $HOME/.acaclaw/start.sh"
$shortcut.WindowStyle = 7  # 最小化

WSL2 桌面集成汇总

安装完成后，Windows 桌面上有两个快捷方式：

WSL2 前置要求

Node.js、npm 和 Conda 由安装脚本在 WSL2 内部安装 — 无需在 Windows 侧安装 Node.js。

安装脚本做了什么

桌面快捷方式（步骤 6b）按平台分：

步骤 6–6b 在网关启动之前执行。这确保即使网关或浏览器启动失败（WSL2 上因 systemd 问题常见），管理脚本和桌面快捷方式也始终可用。

向导随后创建 Conda 环境、保存配置、创建 ~/AcaClaw/ 结构。除包下载与密钥测试外，不向互联网发送你的私密数据。

安装脚本写入的配置文件

安装脚本写入以下配置和设置文件。升级（在已有安装上重新运行安装脚本）时，除特别注明外，所有文件均会被覆盖。

~/.openclaw/（OpenClaw 配置目录）

~/.acaclaw/config/（AcaClaw 配置目录）

~/AcaClaw/.acaclaw/（工作区元数据）

~/.acaclaw/miniforge3/.condarc（Conda 频道配置）

安装脚本复制的其他文件

注意： ~/.condarc（用户级）在安装过程中会被临时备份并移除，安装完成后通过 shell trap 恢复。不会被永久修改。

网络镜像与超时配置

安装脚本在主源响应过慢或不可达时，自动回退到更快的镜像。这在防火墙后或 GitHub/npm 被限速的地区尤其有用。

各来源的回退链：

通过环境变量覆盖：

所有镜像地址和超时值均可配置，在运行安装脚本前设置即可：

# nvm 安装脚本镜像（墙内用户使用 gitee 镜像）
export NVM_MIRROR="https://gitee.com/mirrors/nvm/raw/master/install.sh"  # 默认值

# Node.js 二进制下载镜像（自动检测，或手动设置）
export NVM_NODEJS_ORG_MIRROR="https://npmmirror.com/mirrors/node/"  # 默认值：自动检测

# GitHub 镜像代理（github.com 克隆慢时使用）
export GITHUB_MIRROR="https://ghproxy.com"          # 默认值

# ClawHub 技能注册表镜像
export CLAWHUB_MIRROR="https://cn.clawhub-mirror.com"  # 默认值

# 单个技能安装超时（秒），超时后回退到镜像
export CLAWHUB_SKILL_TIMEOUT=15                      # 默认值

# npm 安装超时（秒），用于 openclaw 和 clawhub CLI
export NETWORK_TIMEOUT=60                            # 默认值

示例：使用自定义 GitHub 镜像和更长的超时时间：

GITHUB_MIRROR="https://mirror.ghproxy.com" NETWORK_TIMEOUT=120 bash install.sh

若已安装 OpenClaw：AcaClaw 不会修改 ~/.openclaw/。卸载 AcaClaw 后，你的 OpenClaw 配置保持不变。

卸载

AcaClaw 支持两种卸载方式：通过浏览器 GUI 或终端。

方式 1：浏览器 GUI（设置页面）

打开 AcaClaw → 导航至 Settings → 点击 Uninstall 标签。

卸载标签显示：

• 将被删除的内容与保留的内容
• Remove AcaClaw only — 仅移除 AcaClaw，保留 OpenClaw
• Remove everything — 同时移除 AcaClaw 和 OpenClaw

点击按钮、确认后卸载开始执行，实时显示进度日志。无需终端。

方式 2：终端

移除 AcaClaw 和 OpenClaw：

bash ~/.acaclaw/uninstall.sh

脚本选项

删除内容

保留内容

卸载脚本不会自动删除 ~/AcaClaw/ — 研究文件归你所有。