← 首页← 文章列表

让 Claude Code 控制浏览器（Termux 手机版）

2026-05-31·📖 6 分钟·TermuxClaude Code浏览器自动化教程

让 Claude Code 控制浏览器（Termux 手机版）

在 Termux 里运行 Firefox，让 Claude Code（AI）自动控制浏览器 全程手机操作，不需要电脑和 ADB 纯 Termux 原生环境，不使用 proot，不使用 musl

📚 相关教程

目录

  1. 原理
  2. 前提
  3. 安装
  4. 启动浏览器
  5. 连接 Claude Code
  6. 实战测试
  7. 进阶配置
  8. 一键脚本
  9. 常见问题

1. 原理

你在 Claude 里提需求
        ↓
Claude Code 调用 tbp-mcp（MCP 服务）
        ↓
tbp-mcp 操作 Firefox（在虚拟显示器里运行）
        ↓
Firefox 执行：打开网页 / 点击 / 输入 / 截图 / 提取文字

这套方案用了一个"虚拟显示器"（Xvfb），让 Firefox 在手机后台运行，不需要在手机屏幕上显示。所有操作通过 xdotool（模拟鼠标键盘）和 xclip（剪贴板注入 JS）完成。

2. 前提

如果你还没配置 Termux，先看《Termux环境配置教程》，完成后再回来：

👉 Termux环境配置教程

包含：F-Droid 安装 → 换源 → pkg update → 存储权限

3. 安装

打开 Termux，逐条输入下面的命令，输完一条按回车，等跑完再输下一条。

3.1 添加软件源

bash
pkg install -y x11-repo tur-repo

3.2 安装浏览器 + 自动化工具

bash
pkg install -y firefox xorg-server-xvfb xdotool xclip openbox imagemagick python3 git

每个包的作用：

包名干啥的
firefox浏览器本体
xorg-server-xvfb虚拟显示器（让浏览器在后台运行）
xdotool模拟鼠标点击和键盘输入
xclip读写剪贴板（用来往浏览器里注入 JS）
openbox窗口管理器（给 Firefox 一个桌面环境）
imagemagick截图工具
python3 / git运行 tbp 所需

3.3 下载浏览器自动化工具

bash
git clone https://github.com/salviz/termux-browser-pilot.git
bash
cd termux-browser-pilot

3.4 安装

bash
pip install --break-system-packages .

安装完成后，tbp 和 tbp-mcp 两个命令就可以用了。

验证一下：

bash
tbp --version

看到 tbp 0.1.0a1 之类的版本号就对了。

4. 启动浏览器

有两种方式启动浏览器：手动模式（推荐，最稳定）和 tbp 模式。

4.1 手动模式（推荐）

新手建议用手动模式，每一步自己控制，出了问题也知道怎么排查。

启动虚拟显示器

bash
Xvfb :99 -screen 0 1920x1080x24 &

启动窗口管理器

bash
DISPLAY=:99 openbox &

启动 Firefox

bash
DISPLAY=:99 firefox --no-remote about:blank &

启动后等 10 秒让 Firefox 完全加载。

验证浏览器正常运行

bash
DISPLAY=:99 xdotool search --name Firefox

能看到输出窗口 ID 列表（比如 2097153），说明 Firefox 跑起来了。

截图测试

bash
DISPLAY=:99 import -window root ~/test.png
bash
ls -la ~/test.png

能看到截图文件说明一切正常。

4.2 tbp 模式

如果想一键启动，也可以用 tbp：

bash
tbp start

这个命令会自动启动虚拟显示器 + 窗口管理器 + Firefox。 如果卡住超过 20 秒，请用手动模式。

4.3 tbp 常用命令

已经启动浏览器后，可以用 tbp 快速操作：

bash
tbp goto https://example.com
bash
tbp text

提取当前页面的文字内容。

bash
tbp screenshot page.png

截取当前页面。

bash
tbp --help

查看所有命令。

5. 连接 Claude Code

这是核心步骤——让 Claude 能直接控制浏览器。

5.1 配置 MCP 服务

bash
cp ~/termux-browser-pilot/.mcp.json ~/.claude/

这个文件告诉 Claude Code："启动的时候，自动加载浏览器控制工具"。

.mcp.json 的内容是这样的（你不需要改它，了解即可）：

json
{
  "mcpServers": {
    "tbp": {
      "command": "tbp-mcp",
      "args": []
    }
  }
}

5.2 启动 Claude Code

bash
cd ~ && claude

第一次启动会检查 MCP 配置。如果看到类似这样的提示：

MCP 服务 tbp 已加载

说明连接成功了。

5.3 确认 MCP 工具可用

在 Claude 中输入：

你现在有哪些工具可以用？列出所有可用的 MCP 工具

Claude 应该会列出浏览器相关工具，比如 browser_navigate（导航）、browser_click（点击）、browser_screenshot（截图）等。

如果看不到这些工具，重启 Claude Code。

6. 实战测试

让 Claude 控制浏览器执行一些任务。

6.1 打开网页

在 Claude 里输入：

帮我打开 https://news.ycombinator.com

6.2 提取内容

提取当前页面上的所有标题和链接

6.3 点击操作

找到页面顶部的 "new" 链接并点击

6.4 搜索功能

在当前页面找到搜索框，输入 "AI"，然后按回车

6.5 截图保存

给当前页面截个图，保存为 screenshot.png

6.6 完成后退回

操作完成后，在 Claude 里输入 /bye 退出。

7. 进阶配置

7.1 改用 Chromium

如果你更喜欢 Chromium（支持 CDP 协议，功能更强）：

bash
pkg install -y chromium
bash
DISPLAY=:99 chromium-browser --no-remote --disable-gpu about:blank &

用 tbp 启动：

bash
tbp start --browser chromium

7.2 管理后台进程

查看虚拟显示器是否在运行：

bash
ps | grep Xvfb

查看 Firefox 是否在运行：

bash
ps | grep firefox

彻底清理所有进程：

bash
pkill firefox
pkill Xvfb
pkill openbox

7.3 开机自启

每次重启手机后，想让浏览器自动启动，配合 Termux:Boot：

bash
mkdir -p ~/.termux/boot
bash
cat > ~/.termux/boot/browser.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/sh
Xvfb :99 -screen 0 1920x1080x24 &
sleep 3
DISPLAY=:99 openbox &
sleep 2
DISPLAY=:99 firefox --no-remote about:blank &
EOF
bash
chmod 700 ~/.termux/boot/browser.sh

7.4 多 Claude 配置

如果你有多个 Claude 配置（比如不同的 API Key），可以创建不同的启动命令：

bash
cat > $PREFIX/bin/claude-browser << 'EOF'
#!/data/data/com.termux/files/usr/bin/sh
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-你的密钥
export ANTHROPIC_MODEL=deepseek-v4-flash
exec claude "$@"
EOF
bash
chmod +x $PREFIX/bin/claude-browser

之后用 claude-browser 启动，会自动带上浏览器 MCP 工具。

7.5 配合 tmux 使用

开三个面板，一个跑 Xvfb/Firefox，一个跑 Claude，一个备用：

bash
tmux

按 Ctrl+b % 垂直分屏，按 Ctrl+b " 水平分屏。在一个面板里启动浏览器，另一个面板里启动 Claude。

断开 tmux（按 Ctrl+b d）后，浏览器和 Claude 都在后台继续运行。

重新连接：

bash
tmux attach

8. 一键脚本

复制下面全部内容，在 Termux 里长按粘贴，按回车：

bash
set -e
echo "=== 1. 安装依赖 ==="
pkg install -y x11-repo tur-repo
pkg install -y firefox xorg-server-xvfb xdotool xclip openbox imagemagick python3 git

echo "=== 2. 安装 tbp ==="
cd ~ && git clone https://github.com/salviz/termux-browser-pilot.git
cd termux-browser-pilot && pip install --break-system-packages .

echo "=== 3. 配置 MCP ==="
cp .mcp.json ~/.claude/

...

8. 常见问题

Q: Firefox 启动失败

bash
pkill firefox
pkill Xvfb
# 重新按第 4 节的步骤来一遍

Q: Claude 说找不到浏览器工具

重启 Claude Code：

bash
claude

MCP 配置只在启动时加载。

Q: 截图全是黑色

Firefox 还没加载完，多等几秒再截图。

或者用 xdotool search --name Firefox 确认浏览器窗口存在后再截图。

Q: xdotool 说 DISPLAY 为空

xdotool 命令前面要加 DISPLAY=:99：

bash
DISPLAY=:99 xdotool search --name Firefox

Q: 运行一段时间后浏览器卡住

bash
pkill firefox
pkill Xvfb
DISPLAY=:99 firefox --no-remote about:blank &

Q: tbp start 一直卡着不动

用手动模式代替（见第 4.1 节）。手动模式更稳定。

如果遇到问题，确认每个命令都成功执行了再继续下一步。