OpenClaw 浏览器技能配置指南 · Ubuntu 24.04 服务器环境开篇$ openclaw browser status running:falsebrowser: unknown看到这个输出我知道浏览器没装好。一开始我以为很简单 — 装个 Chrome 不就行了结果花了大半天踩了 5 个坑中文字体缺失网页全是方框没有图形界面报错 “Unable to open X display”root 用户运行报错 “sandbox not supported”依赖包冲突dpkg 安装失败配置改了不生效忘了重启 Gateway这篇文章记录完整的安装和配置过程帮你节省时间。一、为什么需要在服务器装浏览器你可能会有疑问服务器不是应该跑服务吗为什么要装浏览器原因是 OpenClaw 的浏览器自动化能力。OpenClaw 的browser技能需要调用 Chrome 浏览器来场景说明反爬严格的网站知乎、微信公众号等web_fetch经常 403需要登录的网站通过 Chrome Relay 接管已登录的浏览器会话动态渲染的页面JavaScript 加载的内容web_fetch抓不到如果你只用web_fetch技能确实不需要浏览器。但遇到上面这些场景浏览器是唯一可靠的选择。二、安装流程概览否是否是开始更新软件源 apt update安装依赖包 fonts-liberation 等安装 Chrome dpkg -i安装成功apt --fix-broken install验证 which google-chrome配置 OpenClaw 4 个参数重启 Gateway启动浏览器验证状态running: true?查看日志排查完成 ✅下面是详细步骤。三、正确的安装流程Ubuntu 24.04 服务器环境root 权限。步骤 1更新软件源aptupdate这一步别省有时候安装失败只是因为软件源太旧。步骤 2安装依赖包aptinstall-yfonts-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.debapt--fix-brokeninstall-y方式 B现场下载wgethttps://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb dpkg-igoogle-chrome-stable_current_amd64.debapt--fix-brokeninstall-yapt --fix-broken install这一步很关键它会自动安装 Chrome 需要的依赖。步骤 4验证 Chrome 安装whichgoogle-chrome应返回/usr/bin/google-chrome如果没有返回说明安装失败检查上面的步骤。四、OpenClaw 配置的关键点Chrome 装好了但 OpenClaw 还是用不了。原因是 OpenClaw 有自己的浏览器配置需要告诉它Chrome 装在哪用什么模式运行headless是否允许 root 用户运行noSandbox配置命令# 设置默认使用 openclaw 模式openclaw configsetbrowser.defaultProfileopenclaw# 开启无桌面模式服务器没有图形界面openclaw configsetbrowser.headlesstrue# 强制开启 NoSandboxroot 用户运行必需openclaw configsetbrowser.noSandboxtrue# 设置 Chrome 路径openclaw configsetbrowser.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 Gatewayopenclaw 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中文字体显示为方框 ❌现象浏览器能启动但中文网页显示异常文字全是方框。原因缺少中文字体。解决aptinstall-yfonts-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 configsetbrowser.headlesstrueopenclaw 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 configsetbrowser.noSandboxtrueopenclaw gateway restart注意noSandbox 会降低安全性但在服务器环境只有你访问是可以接受的。坑 4依赖包冲突现象dpkg -i安装失败提示dependency problems - leaving unconfigured原因Chrome 需要一些系统库但 Ubuntu 最小化安装时没有预装。解决apt--fix-brokeninstall-y这条命令会自动安装缺失的依赖。坑 5浏览器启动成功但 OpenClaw 用不了现象openclaw browser status显示running: false。原因Gateway 没有加载最新的浏览器配置。解决openclaw gateway restart openclaw browser start注意配置变更后必须重启 Gateway否则不生效。六、验证清单 命令速查验证清单安装完成后按顺序检查which google-chrome返回/usr/bin/google-chromeopenclaw browser status显示running: true能正常访问中文网页字体正常能用浏览器技能抓取网页如知乎、微信公众号命令速查# 查看浏览器状态openclaw browser status# 启动浏览器openclaw browser start# 停止浏览器openclaw browser stop# 查看浏览器日志openclaw browser logs# 查看 Chrome 路径whichgoogle-chrome# 重启 Gatewayopenclaw gateway restart收尾这篇文章记录了我完整的安装和配置过程。核心就两点依赖包要装全— 特别是fonts-noto-cjk不装中文全是方框OpenClaw 配置要正确—headless和noSandbox必须开改了配置要重启 Gateway如果你遇到问题先检查这两点大概率能解决。最后浏览器装好后你可以试试 OpenClaw 的浏览器技能# 打开一个网页openclaw browseropenhttps://www.example.com# 截图openclaw browser screenshot# 抓取内容openclaw browser snapshot这才是装浏览器的真正目的 — 让 OpenClaw 能帮你操作网页。
在 OpenClaw上装神器Chrome浏览器技能，踩了这 5 个坑，终于安装成功！
OpenClaw 浏览器技能配置指南 · Ubuntu 24.04 服务器环境开篇$ openclaw browser status running:falsebrowser: unknown看到这个输出我知道浏览器没装好。一开始我以为很简单 — 装个 Chrome 不就行了结果花了大半天踩了 5 个坑中文字体缺失网页全是方框没有图形界面报错 “Unable to open X display”root 用户运行报错 “sandbox not supported”依赖包冲突dpkg 安装失败配置改了不生效忘了重启 Gateway这篇文章记录完整的安装和配置过程帮你节省时间。一、为什么需要在服务器装浏览器你可能会有疑问服务器不是应该跑服务吗为什么要装浏览器原因是 OpenClaw 的浏览器自动化能力。OpenClaw 的browser技能需要调用 Chrome 浏览器来场景说明反爬严格的网站知乎、微信公众号等web_fetch经常 403需要登录的网站通过 Chrome Relay 接管已登录的浏览器会话动态渲染的页面JavaScript 加载的内容web_fetch抓不到如果你只用web_fetch技能确实不需要浏览器。但遇到上面这些场景浏览器是唯一可靠的选择。二、安装流程概览否是否是开始更新软件源 apt update安装依赖包 fonts-liberation 等安装 Chrome dpkg -i安装成功apt --fix-broken install验证 which google-chrome配置 OpenClaw 4 个参数重启 Gateway启动浏览器验证状态running: true?查看日志排查完成 ✅下面是详细步骤。三、正确的安装流程Ubuntu 24.04 服务器环境root 权限。步骤 1更新软件源aptupdate这一步别省有时候安装失败只是因为软件源太旧。步骤 2安装依赖包aptinstall-yfonts-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.debapt--fix-brokeninstall-y方式 B现场下载wgethttps://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb dpkg-igoogle-chrome-stable_current_amd64.debapt--fix-brokeninstall-yapt --fix-broken install这一步很关键它会自动安装 Chrome 需要的依赖。步骤 4验证 Chrome 安装whichgoogle-chrome应返回/usr/bin/google-chrome如果没有返回说明安装失败检查上面的步骤。四、OpenClaw 配置的关键点Chrome 装好了但 OpenClaw 还是用不了。原因是 OpenClaw 有自己的浏览器配置需要告诉它Chrome 装在哪用什么模式运行headless是否允许 root 用户运行noSandbox配置命令# 设置默认使用 openclaw 模式openclaw configsetbrowser.defaultProfileopenclaw# 开启无桌面模式服务器没有图形界面openclaw configsetbrowser.headlesstrue# 强制开启 NoSandboxroot 用户运行必需openclaw configsetbrowser.noSandboxtrue# 设置 Chrome 路径openclaw configsetbrowser.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 Gatewayopenclaw 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中文字体显示为方框 ❌现象浏览器能启动但中文网页显示异常文字全是方框。原因缺少中文字体。解决aptinstall-yfonts-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 configsetbrowser.headlesstrueopenclaw 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 configsetbrowser.noSandboxtrueopenclaw gateway restart注意noSandbox 会降低安全性但在服务器环境只有你访问是可以接受的。坑 4依赖包冲突现象dpkg -i安装失败提示dependency problems - leaving unconfigured原因Chrome 需要一些系统库但 Ubuntu 最小化安装时没有预装。解决apt--fix-brokeninstall-y这条命令会自动安装缺失的依赖。坑 5浏览器启动成功但 OpenClaw 用不了现象openclaw browser status显示running: false。原因Gateway 没有加载最新的浏览器配置。解决openclaw gateway restart openclaw browser start注意配置变更后必须重启 Gateway否则不生效。六、验证清单 命令速查验证清单安装完成后按顺序检查which google-chrome返回/usr/bin/google-chromeopenclaw browser status显示running: true能正常访问中文网页字体正常能用浏览器技能抓取网页如知乎、微信公众号命令速查# 查看浏览器状态openclaw browser status# 启动浏览器openclaw browser start# 停止浏览器openclaw browser stop# 查看浏览器日志openclaw browser logs# 查看 Chrome 路径whichgoogle-chrome# 重启 Gatewayopenclaw gateway restart收尾这篇文章记录了我完整的安装和配置过程。核心就两点依赖包要装全— 特别是fonts-noto-cjk不装中文全是方框OpenClaw 配置要正确—headless和noSandbox必须开改了配置要重启 Gateway如果你遇到问题先检查这两点大概率能解决。最后浏览器装好后你可以试试 OpenClaw 的浏览器技能# 打开一个网页openclaw browseropenhttps://www.example.com# 截图openclaw browser screenshot# 抓取内容openclaw browser snapshot这才是装浏览器的真正目的 — 让 OpenClaw 能帮你操作网页。
