doubao-cli：在终端里直接和豆包对话的命令行工具安装与使用指南
作为开发者，你是否经常需要在终端工作时切换到浏览器去问豆包一个问题？doubao-cli 让这一切成为历史——它是一个功能强大的豆包命令行客户端，支持无头模式（Headless）和macOS桌面模式，让你在终端里直接与豆包对话、管理会话、调用MCP工具，甚至运行自动化任务。
| 项目名称 | doubao-cli |
|---|---|
| 仓库地址 | https://github.com/Fullstop000/doubao-cli |
| 官方网站 | npm - doubao-cli |
| 最新更新时间 | 2026-10-22 |
| 项目定位 | 豆包AI命令行客户端，支持Headless和桌面CDP双后端 |
| 开源协议 | MIT |
项目背景
在AI编程时代，开发者每天都在终端里度过大量时间——写代码、跑命令、看日志、查文档。每次需要查个资料、调试个问题、生成一段代码，都要切换到浏览器打开豆包网页，登录、等待加载、输入问题，再切回终端。这种上下文切换不仅打断心流，还严重降低工作效率。
doubao-cli 正是为了解决这个问题而生。它通过两种后端模式连接豆包：一种是Headless无头模式，通过HTTPS协议直接与豆包服务器通信，无需浏览器；另一种是macOS桌面模式，通过CDP协议控制本地安装的豆包桌面客户端。无论哪种模式，都能让你在终端里直接与豆包交互，获得完整的AI对话能力。
除了基本的对话功能，doubao-cli 还支持会话管理（创建、读取、发送消息、等待结果）、模型切换（选择不同参数级别的模型）、MCP工具注册、自动化任务创建、项目工作区关联等高级功能。它不仅是一个聊天工具，更是一个可以深度集成到开发工作流中的AI终端助手。
核心特性
- 💻 双后端架构 — 支持Headless无头模式（Linux/macOS通用）和macOS桌面模式（通过CDP连接豆包客户端），根据操作系统自动选择最佳后端。
- 💬 完整会话管理 — 支持创建会话、读取历史、发送消息、等待回复、停止任务，完整的对话生命周期管理。
- 🧠 多模型切换 — 可查看和选择豆包提供的各种模型，支持调整推理深度（low/medium/high/xhigh/max）。
- 🔧 MCP工具集成 — 支持注册MCP服务器，让豆包AI可以调用外部工具和数据源，扩展能力边界。
- 🎯 Goal模式 — 支持目标导向的任务执行模式，让AI自主规划和完成复杂任务。
- 📁 项目工作区 — 可以将会话关联到本地项目目录，让AI在指定代码仓库上下文中工作。
- 📊 JSON输出 — 所有命令都支持
--json参数，方便脚本化集成和自动化处理。 - 🔄 自动更新 — 内置更新检查和自动更新机制，保持始终为最新版本。
环境要求
| 项目 | 要求 |
|---|---|
| Node.js | ≥ 22.0.0（必须是22以上大版本） |
| 操作系统（Headless模式） | Linux 或 macOS |
| 操作系统（桌面模式） | 仅 macOS，需安装 DoubaoWork.app 或 Doubao.app |
| 豆包账号 | 已注册的豆包账号 |
| 网络 | 能够访问豆包服务器 |
详细部署步骤
第一步：安装 Node.js 22+
doubao-cli 要求 Node.js 22 或更高版本，这是硬性要求。
# 检查当前Node版本
node --version
# 如果版本低于22，需要升级
# macOS（使用nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# 验证版本
node --version
# 应输出 v22.x.x 或更高第二步：全局安装 doubao-cli
# 使用npm全局安装
npm install --global doubao-cli@latest
# 验证安装
doubao --version安装完成后，doubao 命令会全局可用。
第三步：登录豆包账号
根据你使用的模式不同，登录方式也不同：
Headless模式（Linux/macOS通用，推荐）：
# 启动登录流程
doubao headless login
# 终端会显示一个二维码
# 打开手机上的豆包App，扫码并确认登录
# 登录成功后，会话会自动保存macOS桌面模式：
# 启动桌面CDP连接
doubao cdp launch
# 在弹出的豆包桌面应用中登录账号
# 保持聊天窗口打开状态Cookie文件方式（高级）：
# 也可以使用已保存的Cookie文件登录
doubao headless login --cookie-file /path/to/cookies.txt第四步：验证安装
# 查看状态
doubao status --json
# 查看支持的模型列表
doubao models --json
# 查看当前配置文件
doubao profiles --json如果状态显示已登录、模型列表正常返回，说明安装成功。
后端模式选择说明
| 命令 | 使用后端 | 说明 |
|---|---|---|
doubao（Linux默认） |
Headless | 无头HTTPS模式 |
doubao（macOS默认） |
桌面应用（如已安装） | 优先使用豆包工作客户端 |
doubao headless |
Headless | 强制使用无头模式 |
doubao web |
Headless | 兼容别名，等同headless |
doubao --app work |
豆包工作桌面版 | 指定使用工作客户端 |
注意：每次对话请保持使用相同的后端、账号和配置文件，避免会话混乱。
常见坑与解决办法
问题1：Node.js版本不够
doubao-cli 严格要求 Node.js 22+，低版本会直接报错。请使用 nvm 或 n 版本管理器升级到Node 22。
问题2：Headless登录失败
确保手机豆包App是最新版本，扫码时网络畅通。如果二维码过期，重新运行 doubao headless login。
问题3：桌面模式连接失败
macOS桌面模式需要先安装豆包桌面客户端（Doubao.app 或 DoubaoWork.app），且保持应用在运行状态。重启应用需要确认（脚本模式加 --yes）。
问题4：命令超时无响应
复杂任务可能需要更长时间。可以通过 --timeout 参数调整超时时间（单位秒，默认120秒）。
使用方法示例
基本对话
# 创建新会话并发送消息，等待回复
doubao sessions create "帮我写一个Python快速排序算法" --wait --json
# 在已有会话中继续发送消息
doubao sessions send <conversation-id> "加上单元测试" --wait --json
# 读取会话历史
doubao sessions read <conversation-id> --limit 5 --json使用不同模型
# 查看所有可用模型
doubao models --json
# 选择指定模型并设置推理深度
doubao model select 'Orange 5.5' --reasoning max
# 单独调整推理深度
doubao model reasoning highGoal目标模式
# 创建一个目标导向任务
doubao sessions create "搭建一个React + TypeScript的Todo List应用，包含增删改查和本地存储" \
--mode goal \
--runtime cloud \
--wait --json注册MCP工具
# 注册一个MCP服务器
doubao mcp register my-tools \
--command /usr/local/bin/node \
--arg /path/to/my-server.mjs
# 查看已注册的MCP工具
doubao mcp list --json
# 在会话中使用MCP工具
doubao sessions create "使用我的工具查询数据库" --mcp my-tools --permission AskOnRisk --wait自动化任务
# 列出自动化任务
doubao automations list --json
# 创建自动化任务
doubao automations create --file task.json --json
# 查看任务详情
doubao automations get <task-id> --json更新管理
# 检查更新
doubao update check
# 手动更新
doubao update
# 开启自动更新
doubao update auto on
# 查看自动更新状态
doubao update auto status环境变量配置
| 环境变量 | 说明 |
|---|---|
DOUBAO_APP |
桌面应用自定义路径 |
DOUBAO_DATA_DIR |
应用数据目录 |
DOUBAO_CLI_CONFIG_DIR |
配置和恢复目录 |
DOUBAO_HEADLESS_COOKIE |
Headless模式Cookie（敏感信息） |
DOUBAO_CLI_DISABLE_AUTO_UPDATE |
设为1可禁用自动更新提醒 |
常见问题FAQ
Q：doubao-cli 需要付费吗？
A：工具本身完全免费开源（MIT协议）。它使用的是你自己的豆包账号，消耗的是豆包官方的免费额度或你的会员权益。
Q：Headless模式和桌面模式有什么区别？
A：Headless模式通过HTTPS直接与豆包服务器通信，不需要打开浏览器，资源占用低，适合服务器和无GUI环境。桌面模式通过CDP控制本地豆包客户端，功能更完整，但仅支持macOS。
Q：会话会保存在哪里？
A：Headless模式的会话保存在豆包服务器端；桌面模式的会话从客户端的IndexedDB中读取。两者可能存在覆盖范围差异。
Q：支持上传文件吗？
A：支持。使用 --attach 参数可以附加文件，最多50个文件，每个不超过100MiB。
Q：如何集成到我的脚本中？
A：所有命令都支持 --json 输出，你可以在Shell脚本、Python程序中调用doubao-cli并解析JSON结果。
跳转链接
- 🔥 GitHub仓库：https://github.com/Fullstop000/doubao-cli
- 📦 npm包：https://www.npmjs.com/package/doubao-cli
- 📖 详细文档：官方README
- 🌐 豆包官网：https://www.doubao.com