doubao-browser-agent：免费的豆包AI编码代理安装与使用指南

想要体验Claude Code或Cursor那样的AI编程助手，但不想花API费用？doubao-browser-agent 就是你的免费替代品——它通过Playwright控制浏览器自动与豆包对话，把本地文件系统和终端作为工具开放给AI，让豆包帮你写代码、建项目、执行命令，完全免费，无需API Key。

项目名称	doubao-browser-agent
仓库地址	https://github.com/readfor/doubao-browser-agent
官方网站	npm - doubao-browser-agent
最新更新时间	2026-06-23（v1.11.3）
项目定位	基于豆包网页端的自主AI编码代理，免费替代Claude Code/Cursor
开源协议	MIT

项目背景

AI编程助手近年来非常火爆，Claude Code、Cursor、Windsurf等工具让开发者效率倍增，但这些工具都需要付费的API Key，每月费用动辄十几到几十美元。对于个人开发者、学生党来说，这笔开销并不小。有没有办法用上顶级AI模型的编程能力，又不用花API费用呢？

doubao-browser-agent 给出了一个巧妙的答案。它不调用任何付费API，而是用Playwright自动化框架控制一个真实的Chromium浏览器，自动打开豆包网页版，把你的编程任务发送给豆包AI，然后解析豆包的回复，提取出工具调用指令，在本地执行——读文件、写文件、跑命令、创建目录，一步步完成你的项目。整个过程就像有一个真人坐在浏览器前操作豆包一样。

这种"浏览器自动化 + 免费AI"的模式，让普通开发者也能零成本享受到AI编码代理的便利。你只需要一个豆包账号，就能获得类似Cursor的体验：让AI帮你创建Express REST API、写Python爬虫、搭建前端项目、修复Bug。工具还内置了完善的安全机制——路径遍历防护、系统目录隔离、文件覆盖备份、命令白名单审计，确保AI不会误删重要文件。

核心特性

🆓 完全免费使用 — 无需API Key，不产生任何费用，直接使用豆包网页版的免费额度，相当于免费拥有了一个AI编程助手。
🤖 自主Agent循环 — 核心Agent循环：发送任务→等待响应→解析工具调用→执行→再发送结果，直到任务完成。
📁 15种文件系统工具 — 支持读文件、写文件、追加内容、查找替换、删除、列目录、创建目录、移动复制等完整文件操作。
💻 Shell命令执行 — AI可以自主执行终端命令，内置安全验证、命令白名单、审计日志，防止危险操作。
🌐 HTTP API服务 — 交互模式下自动启动9527端口HTTP服务，支持多客户端并发提交任务，内置任务队列。
🔒 多层安全防护 — 路径遍历防护、系统文件隔离、文件覆盖自动备份、命令安全校验，全方位保护你的数据。
🔄 上下文记忆 — 支持 newChat=false 模式在同一对话中连续交流，AI记住之前的讨论内容。
🎛️ 灵活配置 — 支持全局配置文件和项目级配置文件，自定义最大迭代次数、超时时间、输出长度等参数。

环境要求

项目	要求
Node.js	≥ 18.0.0（LTS推荐）
Chromium浏览器	Playwright自动下载（约150MB）
操作系统	Windows 10+ / macOS / Linux（Ubuntu推荐）
豆包账号	已注册的豆包账号
内存	建议4GB以上（Chromium + Node.js）

详细部署步骤

Windows系统安装

第一步：安装 Node.js

# 如果没有Node.js，使用winget安装
winget install OpenJS.NodeJS.LTS

# 验证安装
node --version
# 应输出 v18.x.x 或更高

第二步：全局安装 doubao-browser-agent

npm install -g doubao-browser-agent

第三步：安装Chromium浏览器

# 安装Chromium（约150MB，首次安装后自动执行）
npx playwright install chromium

Ubuntu/Linux系统安装

第一步：安装 Node.js 20.x

# 添加NodeSource源
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装Node.js和npm
sudo apt install -y nodejs

# 验证
node --version
npm --version

第二步：全局安装 doubao-browser-agent

npm install -g doubao-browser-agent

第三步：安装Chromium和系统依赖

# 安装Chromium浏览器
npx playwright install chromium

# 安装Chromium所需的系统依赖（Linux必须！）
npx playwright install-deps chromium

注意：Linux系统必须执行 install-deps，否则Chromium可能无法正常启动。

第四步：登录豆包（首次使用）

# 启动交互模式，会自动打开浏览器窗口
doubao-agent -i

# 浏览器窗口打开后，在页面中登录你的字节跳动账号
# 登录完成后，回到终端按 Enter 键
# 登录状态会保存，后续无需重复登录

登录成功后，交互模式会自动启动HTTP服务，监听9527端口：

✅ 登录成功
🚀 Server listening on port 9527
❯ 等待任务输入...

第五步：验证使用

打开另一个终端窗口，发送一个测试任务：

curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task": "创建一个Hello World的Python脚本"}'

如果一切正常，AI会自动创建文件并返回结果。

常见坑与解决办法

问题1：Chromium没有自动下载

手动执行安装命令：

npx playwright install chromium
# Linux还需要安装系统依赖：
npx playwright install-deps chromium

问题2：登录会话过期

如果使用一段时间后提示需要重新登录，去掉headless模式重新打开浏览器登录：

doubao-agent --interactive --show-browser

问题3：Agent响应了但没创建文件

可能是豆包网页DOM结构变化导致解析失败。开启debug模式查看原始输出：

doubao-agent --debug -i

问题4：Agent停止响应或循环

运行校准工具自动检测DOM选择器：

node src/calibrate.js

问题5：长任务超时

在配置文件中增大超时时间：

# 编辑 ~/.doubao-agent/config.json
{
  "RESPONSE_TIMEOUT": 300000,
  "STABLE_DELAY": 4000
}

使用方法示例

基本命令

# 启动交互模式（登录 + HTTP服务）
doubao-agent -i

# 指定工作目录
doubao-agent -d /path/to/project -i

# 显示浏览器窗口（非交互模式调试用）
doubao-agent --show-browser

# 开启调试模式
doubao-agent --debug -i

# 短别名
da -i   # 等同于 doubao-agent -i

HTTP API 发送任务

# 提交一个新任务（新对话）
curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task": "创建一个Express REST API，带用户认证功能"}'

# 多轮对话模式（记住之前的上下文）
curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task": "给这个API加上JWT认证", "newChat": false}'

# 查询队列状态
curl http://localhost:9527/status

# 查询单个任务
curl http://localhost:9527/task/abc123

Python调用示例

import requests

response = requests.post(
    'http://localhost:9527/task',
    json={'task': '创建一个Python爬虫，爬取新闻标题'}
)
result = response.json()
print(result['answer'])

配置文件

全局配置文件位置：~/.doubao-agent/config.json

{
  "HEADLESS": true,           // 是否隐藏浏览器窗口（默认true，性能优化）
  "MAX_ITERATIONS": 50,       // 每个任务最大Agent步数
  "STABLE_DELAY": 3000,       // 判定AI完成的静默毫秒数
  "DEBUG": false,              // 是否打印原始AI响应
  "RESPONSE_TIMEOUT": 120000, // 最大等待响应时间（毫秒）
  "MAX_OUTPUT_LENGTH": 8000    // 发送给AI的命令输出最大长度
}

项目级配置：在项目根目录创建 doubao-agent.config.json，会覆盖全局配置。

数据存储位置

~/.doubao-agent/
├── session/          # 浏览器Cookie（登录一次永久有效）
│   └── backups/      # 文件覆盖时的自动备份
├── logs/             # 会话日志（需 --save-log 才保存）
├── server.lock       # HTTP服务进程锁文件
└── config.json       # 全局配置

常见问题FAQ

Q：这个工具真的完全免费吗？

A：工具本身开源免费。它自动化的是豆包网页版，消耗的是豆包官方的免费额度。只要你的豆包账号有免费使用额度，就不产生额外费用。

Q：使用这个工具会封号吗？

A：自动化网页操作可能违反豆包的服务条款。项目作者建议仅用于个人和开发目的，使用风险自负。建议不要用于高频批量操作。

Q：AI能做哪些事情？

A：可以读写本地文件、执行shell命令、创建目录、搜索文件、读取URL内容等。基本上你在终端里能做的事，它都能帮你做。

Q：支持其他AI平台吗？

A：当前版本只支持豆包网页端。项目正在积极开发中，未来可能支持其他免费AI聊天前端。

Q：AI执行危险命令怎么办？

A：内置了多重安全防护：命令白名单模式、路径遍历防护、系统目录隔离、文件覆盖前自动备份。所有操作都会记录审计日志。

跳转链接

🔥 GitHub仓库：https://github.com/readfor/doubao-browser-agent
📦 npm包：https://www.npmjs.com/package/doubao-browser-agent
🚀 安装命令：npm install -g doubao-browser-agent
🌐 豆包官网：https://www.doubao.com
📚 Playwright文档：https://playwright.dev

doubao-browser-agent：免费的豆包AI编码代理