Kali Linux 下 OpenClaw 安装与常见问题排查
本文记录了在 Kali Linux 环境下部署 OpenClaw AI 网关的过程。初始遇到 Dashboard 连接失败（4008 错误），经排查发现网关正常但浏览器端认证异常。后续涉及系统升级、依赖修复、浏览器更新及输入法配置等步骤。
第一部分：OpenClaw 基础安装与启动
1.1 安装 OpenClaw
官方提供了多种安装方式（npm、二进制包等）。验证版本：
openclaw --version
1.2 启动网关
网关是 OpenClaw 的核心服务，必须一直运行。打开终端执行：
openclaw gateway run
你会看到类似下面的日志，说明网关启动成功：
[gateway] listening on ws://127.0.0.1:18789, ws://[::1]:18789 (PID xxxx)
注意： 这个终端不要关，保持前台运行，方便看日志。
1.3 生成 Dashboard 访问链接
另开一个终端，执行：
openclaw dashboard --no-open
它会输出一个类似 http://127.0.0.1:18789/#token=一串字符 的 URL。直接复制这个 URL 到浏览器打开，如果一切正常，你会看到 OpenClaw 的 Web 界面。
第二部分：遇到问题——Dashboard 连接失败（4008 错误）
2.1 现象
浏览器打开 Dashboard 后一直显示'disconnected (4008): connect failed'，但 openclaw tui 能用。
2.2 第一步：确认网关是否活着
用 websocat 这个工具直接连接 WebSocket 端口（先安装）：
# 安装 websocat（如果没装）
sudo apt install websocat
# 或者从 GitHub 下载
wget https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl -O websocat
chmod +x websocat
sudo mv websocat /usr/local/bin/
# 测试连接
websocat ws://127.0.0.1:18789
如果看到类似 {"type":"event","event":"connect.challenge","payload":{...}} 的消息，说明网关正常，问题出在浏览器端。
2.3 第二步：浏览器 F12 大法
打开浏览器开发者工具（F12）：
- Console：有没有红色错误？我看到的是
An invalid or illegal string was specified。 - Network → 找到 WebSocket 连接 → Messages：浏览器有没有发送
auth消息？我的情况是没有发送，导致网关超时断开。
2.4 第三步：手动注入 Token（临时解决方案）
既然浏览器没自动发 token，我们手动帮它存一下。在浏览器控制台执行：
sessionStorage.setItem('openclaw:gateway:token','你的完整 token');
然后刷新页面。如果连接成功，说明是前端解析 token 的问题。但我的情况是依然失败，怀疑是浏览器版本太老。
2.5 第四步：检查浏览器版本
firefox-esr --version
我的是 102.0，太老了，决定升级到最新 ESR。
第三部分：升级 Firefox 引发的系统依赖修复大作战
3.1 换国内源（加速下载）
编辑源列表：
sudo nano /etc/apt/sources.list
替换为以下内容之一（保留一个）：
deb https://mirrors.tuna.tsinghua.edu.cn/kali kali-rolling main non-free contrib
# 或者中科大： deb https://mirrors.ustc.edu.cn/kali kali-rolling main non-free contrib
# 或者阿里云： deb http://mirrors.aliyun.com/kali kali-rolling main non-free contrib
保存后更新：
sudo apt update
3.2 尝试安装 Firefox
sudo apt install firefox-esr
结果报错：The following packages have unmet dependencies，还有 kali-desktop-xfce 依赖问题。
3.3 修复依赖的通用三板斧
# 修复破损的依赖
sudo apt --fix-broken install
# 重新配置所有未完成的安装
sudo dpkg --configure -a
# 全系统升级（解决深层依赖）
sudo apt full-upgrade -y
3.4 处理 APT 配置文件语法错误
升级过程中提示 /etc/apt/apt.conf.d/80axel 和 /etc/apt/apt.conf.d/99parallel-downloads 有语法错误，直接删除：
sudo rm /etc/apt/apt.conf.d/80axel
sudo rm /etc/apt/apt.conf.d/99parallel-downloads
3.5 处理文件冲突（libgtk 覆盖问题）
遇到 dpkg: error processing archive libgtk-3-0t64 ... trying to overwrite ...，强制覆盖：
sudo dpkg -i --force-overwrite /var/cache/apt/archives/libgtk-3-0t64_*.deb
sudo apt --fix-broken install
3.6 PostgreSQL 升级弹窗
full-upgrade 中途弹出'升级 PostgreSQL 15 到 18'的对话框，果断选 <No>，以免数据库升级失败影响系统。
3.7 Xfce 面板插件崩溃
升级后 Xfce 面板弹窗'Plugin restarted more than once…'，选 Remove 临时移除，等重启后再手动加回来。
3.8 鼠标光标消失（VMware 虚拟机）
重启后鼠标没了，这是 VMware 显卡驱动的问题。创建配置文件强制使用软件光标：
sudo mkdir -p /etc/X11/xorg.conf.d
sudo nano /etc/X11/xorg.conf.d/20-vmware.conf
写入：
Section "Device"
Identifier "VMware SVGA"
Driver "vmware"
Option "HWCursor" "off"
EndSection
保存后重启：sudo reboot，鼠标回归。
3.9 终于装上 Firefox
再次运行 sudo apt install firefox-esr，成功！版本 128+。
3.10 再次测试 Dashboard
用新 Firefox 打开 Dashboard，依然连接失败，但手动注入 token 后刷新——终于成功！看来新浏览器虽然现代了，但 OpenClaw 前端可能还是需要手动存一次 token。之后只要不清理缓存，就能正常使用。
3.11 设备配对（如果还是不行）
如果手动注入 token 后依然失败，可能是设备未配对。查看待批准设备：
openclaw devices list
如果有 pending 状态的设备，批准它：
openclaw devices approve --latest
然后刷新页面。
3.12 临时禁用设备认证（测试用）
如果上述都不行，可以尝试关闭设备认证（仅测试）：
编辑 ~/.openclaw/config.json，在 gateway 部分添加：
{"gateway":{"controlUi":{"dangerouslyDisableDeviceAuth":true}}}
重启网关后测试，如果成功再重新开启并正确配对。
第四部分：安装 OpenClaw 技能（让 AI 能干实事）
4.1 安装技能管理工具 clawhub
# 全局安装
npm install -g clawhub@latest
# 设置 npm 国内镜像（加速）
npm config set registry https://registry.npmmirror.com
# 验证安装
clawhub --version
4.2 用 clawhub 安装技能（推荐）
常用技能：
# 联网搜索
clawhub install tavily-search
# 技能推荐助手
clawhub install find-skills
# 主动迭代（复杂任务处理）
clawhub install proactive-agent
# 办公自动化
clawhub install office-automation
查看已安装技能：
clawhub list
4.3 手动安装技能（备选）
如果技能包是 zip 或 git 仓库，可以手动部署：
# 创建技能文件夹
mkdir -p ~/.openclaw/skills/技能名
# 解压（如果没装 unzip，先装：sudo apt install unzip）
unzip ~/Downloads/技能包.zip -d ~/.openclaw/skills/技能名
# 进入技能目录安装依赖
cd ~/.openclaw/skills/技能名
npm install
# 重启网关
openclaw gateway restart
第五部分：配置中文输入法（谷歌拼音）
折腾完 OpenClaw，发现 Kali 连中文都打不了，于是又掉进了输入法的坑。
5.1 安装 Fcitx 框架和谷歌拼音
sudo apt update
sudo apt install fcitx fcitx-googlepinyin fcitx-config-gtk -y
5.2 安装中文字体（避免显示方块）
sudo apt install fonts-wqy-microhei fonts-wqy-zenhei xfonts-wqy -y
5.3 设置环境变量（全局生效）
编辑 /etc/environment：
sudo nano /etc/environment
在文件末尾添加一行：
XMODIFIERS=@im=fcitx
保存退出。重启系统让变量生效：
sudo reboot
5.4 配置输入法
重启后，打开终端启动 Fcitx（如果没自动启动）：
fcitx -d
然后在应用菜单搜索'Fcitx 配置'并打开，点击左下角 + 添加输入法，取消勾选'仅显示当前语言'，搜索'Google 拼音'并添加。把 Google 拼音上移到首位，方便切换。
5.5 测试输入法
打开 Firefox 或文本编辑器，按 Ctrl+空格 切换输入法，如果屏幕右上角出现小键盘图标，且能打出拼音候选词，说明成功了。
5.6 解决 Fcitx 常见问题
- 如果按快捷键没反应：检查环境变量
echo $XMODIFIERS是否为@im=fcitx，不是的话手动设置并重启 fcitx。 - 如果出现
fcitx-keyboard-us already exists警告：忽略，不影响使用。 - 如果 Fcitx 没自启动：在'会话和启动'中添加自启动项，命令为
fcitx -d。 - 如果环境变量不生效：可以写入
~/.profile或~/.xprofile，但/etc/environment最稳妥。
5.7 修复损坏的 .bashrc
在配置过程中，我的 .bashrc 因误操作损坏，导致终端报错'shopt not found'和提示符变成乱码。解决方法：
# 备份原文件
cp ~/.bashrc ~/.bashrc.bak
# 恢复默认配置
cp /etc/skel/.bashrc ~/
# 重新添加输入法环境变量（可选）
echo 'export GTK_IM_MODULE=fcitx' >> ~/.bashrc
echo 'export QT_IM_MODULE=fcitx' >> ~/.bashrc
echo 'export XMODIFIERS=@im=fcitx' >> ~/.bashrc
source ~/.bashrc
如果 /etc/skel/.bashrc 也不正常，可以直接创建一个最简版本。
第六部分：常用命令速查
# OpenClaw 网关管理
openclaw gateway run # 启动网关
openclaw gateway stop # 停止网关
openclaw gateway restart # 重启网关
openclaw devices list # 查看设备（用于配对）
openclaw devices approve --latest # 批准最新设备
openclaw dashboard --no-open # 生成 Dashboard 链接
# 技能管理
clawhub install 技能名 # 安装技能
clawhub list # 查看已安装技能
clawhub uninstall 技能名 # 卸载技能
# 输入法
fcitx -d # 启动 fcitx
fcitx -r # 重启 fcitx
fcitx-configtool # 打开配置界面
# 系统修复
sudo apt --fix-broken install # 修复依赖
sudo dpkg --configure -a # 重新配置未完成安装
sudo dpkg -i --force-overwrite 包名.deb # 强制覆盖文件冲突
# 查看版本
firefox-esr --version
openclaw --version
总结与避坑指南
- 遇到 WebSocket 连接失败，先用
websocat测网关，快速定位问题。 - 浏览器 F12 是神器，看 Console 错误和 WebSocket 消息，能省不少时间。
- 手动注入 token 是万能备胎，如果自动认证失败，试试在控制台存一次 token。
- 系统升级前务必换国内源，否则等到天荒地老。
- 依赖冲突别怕，
--fix-broken install和dpkg --force-overwrite能解决 90% 的问题。 - PostgreSQL 升级弹窗选 No，安全第一。
- VMware 鼠标消失有解，创建 xorg 配置文件即可。
- 输入法环境变量要全局生效，直接写进
/etc/environment最稳。 - Fcitx 的
XMODIFIERS警告，按本文设置后重启即可消失。 - 技能安装用 clawhub，自动处理依赖，省心省力。
现在我的 Kali 已经能正常使用 OpenClaw，AI 也能联网搜索、处理文档，还能用中文聊天，完美！希望这篇记录能帮你少走弯路，如果在折腾 OpenClaw 时遇到其他奇葩问题，欢迎交流～
