OpenClaw 浏览器技能配置指南 · Ubuntu 24.04 服务器环境

---

开篇

$ openclaw browser status
running: false
browser: unknown

看到这个输出，我知道：浏览器没装好。

一开始我以为很简单 — 装个 Chrome 不就行了？结果花了大半天，踩了 5 个坑：

1. 中文字体缺失，网页全是方框
2. 没有图形界面，报错 “Unable to open X display”
3. root 用户运行，报错 “sandbox not supported”
4. 依赖包冲突，dpkg 安装失败
5. 配置改了不生效，忘了重启 Gateway

这篇文章记录完整的安装和配置过程，帮你节省时间。

---

一、为什么需要在服务器装浏览器？

你可能会有疑问：服务器不是应该跑服务吗？为什么要装浏览器？

原因是 OpenClaw 的浏览器自动化能力。

OpenClaw 的 browser 技能需要调用 Chrome 浏览器来：

场景	说明
反爬严格的网站	知乎、微信公众号等，web_fetch 经常 403
需要登录的网站	通过 Chrome Relay 接管已登录的浏览器会话
动态渲染的页面	JavaScript 加载的内容，web_fetch 抓不到

如果你只用 web_fetch 技能，确实不需要浏览器。但遇到上面这些场景，浏览器是唯一可靠的选择。

---

二、安装流程概览

下面是详细步骤。

---

三、正确的安装流程

Ubuntu 24.04 服务器环境，root 权限。

步骤 1：更新软件源

apt update

这一步别省，有时候安装失败只是因为软件源太旧。

步骤 2：安装依赖包

apt install -y fonts-liberation xdg-utils fonts-noto-cjk

三个包的作用：

包名	作用	不装的后果
fonts-liberation	浏览器字体支持	页面字体显示异常
xdg-utils	桌面工具（OpenClaw 需要）	浏览器无法启动
fonts-noto-cjk	中文字体支持	中文显示为方框 ❌

我踩的坑： 一开始没装 fonts-noto-cjk，浏览器能启动，但中文网页全是方框。

步骤 3：安装 Chrome 浏览器

方式 A：已有安装包

dpkg -i /path/to/google-chrome-stable_current_amd64.deb
apt --fix-broken install -y

方式 B：现场下载

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
dpkg -i google-chrome-stable_current_amd64.deb
apt --fix-broken install -y

apt --fix-broken install 这一步很关键，它会自动安装 Chrome 需要的依赖。

步骤 4：验证 Chrome 安装

which google-chrome

应返回：/usr/bin/google-chrome

如果没有返回，说明安装失败，检查上面的步骤。

---

四、OpenClaw 配置的关键点

Chrome 装好了，但 OpenClaw 还是用不了。

原因是 OpenClaw 有自己的浏览器配置，需要告诉它：

• Chrome 装在哪
• 用什么模式运行（headless）
• 是否允许 root 用户运行（noSandbox）

配置命令

# 设置默认使用 openclaw 模式
openclaw config set browser.defaultProfile "openclaw"

# 开启无桌面模式（服务器没有图形界面）
openclaw config set browser.headless true

# 强制开启 NoSandbox（root 用户运行必需）
openclaw config set browser.noSandbox true

# 设置 Chrome 路径
openclaw config set browser.executablePath "/usr/bin/google-chrome"

关键参数解释

参数	作用	不配置的后果
headless	无头模式（无图形界面运行）	报错 “Unable to open X display”
noSandbox	允许 root 用户运行	报错 “Running as root without --no-sandbox is not supported”
executablePath	告诉 OpenClaw Chrome 在哪	报错 “Chrome executable not found”
defaultProfile	设置默认浏览器模式	不设置则用默认配置

重启 Gateway

配置完成后，重启 OpenClaw Gateway：

openclaw gateway restart

注意： 配置变更后必须重启 Gateway，否则不生效。我一开始就没重启，折腾了半天。

启动浏览器

openclaw browser start

验证状态

openclaw browser status

预期输出：

profile: openclaw
enabled: true
running: true
cdpPort: 18800
browser: custom
detectedPath: /usr/bin/google-chrome

如果 running: false，看下面的故障排除。

---

五、我遇到的 5 个坑 + 解决方案

坑 1：中文字体显示为方框 ❌

现象： 浏览器能启动，但中文网页显示异常，文字全是方框。

原因： 缺少中文字体。

解决：

apt install -y fonts-noto-cjk

安装完成后重启浏览器：

openclaw browser stop
openclaw browser start

坑 2：报错 “Unable to open X display”

现象： 运行 openclaw browser start 失败，报错：

[ERROR:browser_main_loop.cc(1443)] Unable to open X display.

原因： 服务器没有图形界面，但 Chrome 尝试打开 X display。

解决： 确保配置了 browser.headless true。

openclaw config set browser.headless true
openclaw gateway restart

坑 3：报错 “Running as root without --no-sandbox is not supported”

现象： 浏览器启动失败，报错：

[ERROR:zygote_host_impl_linux.cc(100)] Running as root without 
--no-sandbox is not supported. See https://crbug.com/638180.

原因： 用 root 用户运行 Chrome，但没有配置 noSandbox。

解决：

openclaw config set browser.noSandbox true
openclaw gateway restart

注意： noSandbox 会降低安全性，但在服务器环境（只有你访问）是可以接受的。

坑 4：依赖包冲突

现象： dpkg -i 安装失败，提示：

dependency problems - leaving unconfigured

原因： Chrome 需要一些系统库，但 Ubuntu 最小化安装时没有预装。

解决：

apt --fix-broken install -y

这条命令会自动安装缺失的依赖。

坑 5：浏览器启动成功但 OpenClaw 用不了

现象： openclaw browser status 显示 running: false。

原因： Gateway 没有加载最新的浏览器配置。

解决：

openclaw gateway restart
openclaw browser start

注意： 配置变更后必须重启 Gateway，否则不生效。

---

六、验证清单 + 命令速查

验证清单

安装完成后，按顺序检查：

• which google-chrome 返回 /usr/bin/google-chrome
• openclaw browser status 显示 running: true
• 能正常访问中文网页（字体正常）
• 能用浏览器技能抓取网页（如知乎、微信公众号）

命令速查

# 查看浏览器状态
openclaw browser status

# 启动浏览器
openclaw browser start

# 停止浏览器
openclaw browser stop

# 查看浏览器日志
openclaw browser logs

# 查看 Chrome 路径
which google-chrome

# 重启 Gateway
openclaw gateway restart

---

收尾

这篇文章记录了我完整的安装和配置过程。

核心就两点：

1. 依赖包要装全 — 特别是 fonts-noto-cjk，不装中文全是方框
2. OpenClaw 配置要正确 — headless 和 noSandbox 必须开，改了配置要重启 Gateway

如果你遇到问题，先检查这两点，大概率能解决。

最后，浏览器装好后，你可以试试 OpenClaw 的浏览器技能：

# 打开一个网页
openclaw browser open https://www.example.com

# 截图
openclaw browser screenshot

# 抓取内容
openclaw browser snapshot

这才是装浏览器的真正目的 — 让 OpenClaw 能帮你操作网页。

---