本地部署 Camofox-Browser，并接入 Hermes Agent

Camofox是基于 Camoufox（Firefox 的 C++ 级别指纹伪装分支），提供了一个专为 AI 智能体设计的 REST API 服务器。

camofox-browser 在 C++ 引擎层面伪造指纹：navigator.hardwareConcurrency、WebGL 渲染器、AudioContext、屏幕几何尺寸、WebRTC 等，在 JavaScript 执行之前就已经完成伪装。

仓库地址：https://github.com/jo-inc/camofox-browser.git

1. 准备目录

1 2	mkdir -p ~/local-shared-deployments cd ~/local-shared-deployments

2. 拉代码

1 2	git clone https://github.com/jo-inc/camofox-browser.git cd camofox-browser

3. 先下载构建依赖，不要直接起容器

这个项目的 Dockerfile 依赖本地 dist/ 目录里的二进制文件。先跑：

1	make fetch

执行完后，本地应该能看到类似文件：

1 2	dist/camoufox-x86_64.zip dist/yt-dlp-x86_64

如果跳过这一步，后面的 Docker build 很容易直接失败。

4. 写 docker-compose.yaml

在仓库根目录写一个自己的 docker-compose.yaml：

services:
  camofox-browser:
    image: camofox-browser:local
    container_name: camofox-browser
    build:
      context: .
      args:
        ARCH: ${ARCH}
        CAMOUFOX_VERSION: ${CAMOUFOX_VERSION}
        CAMOUFOX_RELEASE: ${CAMOUFOX_RELEASE}
    env_file:
      - .env
    environment:
      CAMOFOX_COOKIES_DIR: /data/cookies
    ports:
      - "127.0.0.1:${CAMOFOX_PORT}:${CAMOFOX_PORT}"
    volumes:
      - ./data/cookies:/data/cookies
    restart: unless-stopped
    shm_size: "1gb"

重点只有四个：

端口只绑定到 127.0.0.1
Cookie 目录做持久化
镜像本地构建
shm_size 给到 1gb

5. 写 .env

在同目录写 .env：

ARCH=x86_64
CAMOUFOX_VERSION=135.0.1
CAMOUFOX_RELEASE=beta.24
CAMOFOX_PORT=9377
NODE_ENV=production
MAX_OLD_SPACE_SIZE=256

CAMOFOX_API_KEY=***
CAMOFOX_ADMIN_KEY=***

MAX_SESSIONS=50
MAX_TABS_PER_SESSION=10
MAX_TABS_GLOBAL=50
MAX_CONCURRENT_PER_USER=3
SESSION_TIMEOUT_MS=1800000
TAB_INACTIVITY_MS=300000
BROWSER_IDLE_TIMEOUT_MS=300000
HANDLER_TIMEOUT_MS=30000

PROMETHEUS_ENABLED=false

PROXY_STRATEGY=
PROXY_PROVIDER=...
PROXY_HOST=
PROXY_PORT=
PROXY_PORTS=
PROXY_USERNAME=
PROXY_PASSWORD=***
PROXY_BACKCONNECT_HOST=
PROXY_BACKCONNECT_PORT=7000

说明：

CAMOFOX_PORT=9377 保持默认值，最省事。
CAMOFOX_API_KEY / CAMOFOX_ADMIN_KEY 是服务自己的鉴权项，博客里不要放真值。
代理项先留空也能启动，后面需要再补。

6. 建持久化目录

1	mkdir -p data/cookies

7. 启动

1	docker compose up -d

8. 健康检查

1	curl http://127.0.0.1:9377/health

正常应返回类似：

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true
}

9. 把 camofox-browser 接到 Hermes Agent

Hermes 这边不需要改 browser tool 的调用方式。它本身已经支持 Camofox 后端，触发条件就是设置 CAMOFOX_URL。

9.1 写 Hermes 的 .env

编辑 ~/.hermes/.env，加一行：

1	CAMOFOX_URL=http://127.0.0.1:9377

9.2 重启 Hermes

改完 ~/.hermes/.env 后，重启 Hermes CLI 或 gateway 进程，让新环境变量生效。

9.3 接入后会发生什么

只要 CAMOFOX_URL 已设置，Hermes 的浏览器工具会自动改走 Camofox REST API，而不是默认的浏览器后端。也就是说，这些工具名都不用改：

browser_navigate
browser_snapshot
browser_click
browser_type
browser_scroll
browser_back
browser_console
browser_get_images
browser_vision

对 agent 来说，还是原来那套 browser 工具；变的只是后端实现。

9.4 怎么验证 Hermes 已经接上

最简单的办法是重启 Hermes 后，让它执行一次正常浏览：

1	打开 https://example.com 看一下页面内容

如果 CAMOFOX_URL 生效，Hermes 的 browser 工具会直接通过本地 Camofox 服务去建 tab、导航、拿 snapshot。

10. 可选：开启 Hermes 管理的持久化会话

如果你希望 Hermes 在多次任务之间尽量复用同一套浏览器身份，而不是每次都走临时会话，可以打开这个配置：

编辑 ~/.hermes/config.yaml：

1
2
3

browser:
  camofox:
    managed_persistence: true

作用：

关闭时：Hermes 给每个浏览器任务分配随机 userId，会话更偏临时。
开启时：Hermes 会按当前 profile 生成稳定的 userId / sessionKey，让 Camofox 更容易把它映射到同一套持久浏览器身份。

这个选项默认是关的。如果只是先跑起来，不开也行。

11. 最短可执行流程

cd ~/local-shared-deployments

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
make fetch
mkdir -p data/cookies
# 写 docker-compose.yaml
# 写 .env

docker compose up -d
curl http://127.0.0.1:9377/health

echo 'CAMOFOX_URL=http://127.0.0.1:9377' >> ~/.hermes/.env
# 重启 Hermes

使用MCP协议接入

{
  "mcpServers": {
    "camofox-browser": {
      "command": "npx",
      "args": ["-y", "camofox-browser-mcp@latest"],
      "env": {
        "CAMOFOX_BASE_URL": "http://127.0.0.1:9377",
        "CAMOFOX_DEFAULT_USER_ID": "trae-agent"
      }
    }
  }
}

12. 常见问题

直接 docker build 失败

项目需要从Github下载依赖，需要先运行 make fetch或者直接使用make up，不能直接构建容器

端口暴露到公网

确认 Compose 里写的是 127.0.0.1:9377:9377，不是裸 9377:9377。

Hermes 没走 Camofox

确认 ~/.hermes/.env 里有 CAMOFOX_URL，并且改完后已经重启 Hermes。

确认 ./data/cookies:/data/cookies 已挂卷。

浏览器行为不稳定

先确认 /health 返回里 browserConnected 和 browserRunning 都是 true。

浏览器引擎在默认 UBO 插件下载/解压步骤失败后永久卡住

日志报错：Failed to download and extract UBO: Error: Failed to download from https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi after 5 attempts

issues：https://github.com/jo-inc/camofox-browser/issues/5067

解决：在合并PR之前，你可以使用科学工具开启Tun模式，然后不带任何参数运行Docker容器，若日志中没有报错且容器内/root/.cache/camoufox/addons/UBO目录存在完整的插件文件，即可封装容器为修复后的镜像，使用修复后的镜像运行服务即可。

13. 脱敏说明

文中的密钥、代理信息、路径细节均已脱敏；流程、配置结构和联动方式保留。