薅Doubao羊毛技术交流

发布日期：2026/2/28 5:51:57 浏览量：

	# 豆包集成原理与测试指南 

	## 一、豆包方案原理 

	### 1. 两种方案对比（优先使用 doubao-proxy） 

	| 方案 | 推荐度 | 说明 |

	|------|--------|------|

	| **doubao-proxy** | ★ 推荐 | 使用 [doubao-free-api](https://github.com/linuxhsj/doubao-free-api) 本地代理，对外提供 OpenAI 兼容接口，更稳定、易调试 |

	| **doubao-web** | 直连备选 | 直接请求豆包网页 API，无额外依赖，但 SSE 格式易变，需维护解析逻辑 |

	**doubao-proxy 使用方式**：本地运行 doubao-free-api 代理（默认 `http://127.0.0.1:8000`），OpenClaw 通过 `Authorization: Bearer` 调用其 OpenAI 兼容的 `/v1/chat/completions` 接口。

	### 2. 总体架构 

	豆包集成使用**网页端 Cookie 认证**，不依赖官方 API Key。原理是：

	```

	浏览器登录豆包 → 捕获 Cookie（sessionid、ttwid 等）→

	  doubao-proxy：传给本地代理，代理内部用 Cookie 调用豆包 API

	  doubao-web：直接用 Cookie 冒充网页请求 → 调用豆包内部 API

	```

	### 3. 技术细节 

	| 环节 | doubao-proxy | doubao-web |

	|------|--------------|------------|

	| **API 端点** | 本地代理 `/v1/chat/completions`（OpenAI 兼容） | `https://www.doubao.com/samantha/chat/completion` |

	| **认证方式** | Bearer Token（sessionid） | Cookie（sessionid、ttwid） |

	| **请求/响应** | 标准 OpenAI 格式 | 豆包自定义 SSE（`event_type` 2001/2003 等） |

	### 4. 数据流（Web UI 发消息时） 

	**doubao-proxy 流程**：

	```

	Web UI → chat.send → runEmbeddedAttempt → authStorage.getApiKey("doubao-proxy")

	  → OpenAI 兼容 fetch(baseUrl/v1/chat/completions, Bearer sessionid)

	  → 本地代理转发到豆包 API → 标准 SSE 流 → Web UI

	```

	**doubao-web 流程**：

	```

	Web UI → chat.send → runEmbeddedAttempt → authStorage.getApiKey("doubao-web")

	  → createDoubaoWebStreamFn(cookie) → DoubaoWebClient.chatCompletions(stream: true)

	  → fetch 豆包 API → 解析自定义 SSE → 推 text_delta → Web UI

	```

	### 5. 关键路径 

	- **认证存储**：`~/.openclaw/agents//auth-profiles.json` 中 `doubao-proxy:default` 或 `doubao-web:default` 

	- **配置**：`openclaw.json` 中 `agents.defaults.model.primary` 为 `doubao-proxy/doubao` 或 `doubao-web/doubao-seed-2.0` 

	- **状态目录**：默认 `~/.openclaw`；若项目内有 `.openclaw-state`，则用项目内目录

	---

	## 二、使用当前项目（非系统 openclaw） 

	### 方式 A：项目内独立状态（推荐） 

	在项目根目录创建 `.openclaw-state`，之后用 `pnpm run openclaw` 时会自动使用该目录：

	```bash

	cd /path/to/openclawWeComzh  # 替换为实际项目路径 

	# 1. 创建项目本地状态目录 

	mkdir -p .openclaw-state 

	# 2. 之后 pnpm run openclaw 会自动使用 .openclaw-state（run-node.mjs 会检测） 

	```

	### 方式 B：显式指定环境变量 

	```bash

	cd /path/to/openclawWeComzh  # 替换为实际项目路径 

	# 使用项目目录下的状态 

	export OPENCLAW_STATE_DIR="$(pwd)/.openclaw-state" 

	pnpm run openclaw onboard 

	```

	---

	## 三、分步测试流程 

	### 步骤 0：准备环境 

	```bash

	cd /path/to/openclawWeComzh  # 替换为实际项目路径 

	# 确保依赖已安装 

	pnpm install 

	# 确保已构建（首次或改代码后） 

	pnpm build 

	```

	### 步骤 1：创建项目本地状态目录 

	```bash

	mkdir -p .openclaw-state 

	```

	（可选：想完全隔离时，可清空 `rm -rf .openclaw-state/*`）

	### 步骤 2：运行 onboard，配置豆包 

	```bash

	pnpm run openclaw onboard 

	```

	在交互中：

	1. 选择 **模型提供者** → 选 **豆包 (Doubao)** 

	2. 选择 **豆包方案**：

	   - **doubao-proxy**（推荐）：需本地运行 [doubao-free-api](https://github.com/linuxhsj/doubao-free-api)，然后输入代理 baseUrl（默认 `http://127.0.0.1:8000`）和 sessionid

	   - **doubao-web**：直连豆包网页 API

	**若选 doubao-proxy**：

	- 先启动 doubao-free-api 代理（Docker: `linuxhsj/doubao-free-api:latest`，或见 [linuxhsj/doubao-free-api](https://github.com/linuxhsj/doubao-free-api) README）

	- 在 onboard 中填写 baseUrl（如 `http://127.0.0.1:8000`）和 sessionid

	- 认证存为 `DOUBAO_PROXY_SESSIONID` 或 `auth-profiles.json` 中 `doubao-proxy:default` 

	**若选 doubao-web**：

	- **自动登录**：会启动 Chrome，打开豆包页面，扫码登录后脚本自动捕获 Cookie

	- **使用现有 Chrome**：需先以调试模式启动 Chrome：

	  ```bash

	  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 

	  ```

	  然后在 Chrome 中登录 https://www.doubao.com/chat/，再在 onboard 中选「使用现有 Chrome」

	- **手动粘贴**：在浏览器 DevTools → Application → Cookies 中复制 `sessionid` 和 `ttwid` 粘贴进去

	### 步骤 3：验证认证是否写入 

	```bash

	# 查看 auth-profiles（路径取决于你的 agentId，通常为 main） 

	cat .openclaw-state/agents/main/agent/auth-profiles.json | head -80 

	```

	应能看到 `doubao-proxy:default` 或 `doubao-web:default` 以及对应的 credential。

	### 步骤 4：确认默认模型为豆包 

	```bash

	cat .openclaw-state/openclaw.json 

	```

	检查 `agents.defaults.model.primary`：

	- doubao-proxy：应为 `doubao-proxy/doubao` 

	- doubao-web：应为 `doubao-web/doubao-seed-2.0` 

	### 步骤 5：单独测试豆包 API（绕过 OpenClaw 流程） 

	**doubao-proxy**：用 curl 测试代理是否正常：

	```bash

	curl -N -X POST "http://127.0.0.1:8000/v1/chat/completions" \ 

	  -H "Authorization: Bearer <你的sessionid>" \ 

	  -H "Content-Type: application/json" \ 

	  -d ’{"model":"doubao","messages":[{"role":"user","content":"你好"}],"stream":true}’ 

	```

	**doubao-web**：修改 `test-doubao-integration.js` 中的 `TEST_AUTH`，填入 sessionid 等，然后：

	```bash

	node test-doubao-integration.js 

	```

	若能正常返回流式内容，说明 API 与认证没问题，问题在 OpenClaw 内部流程。

	### 步骤 6：启动 Gateway 和 Web UI 

	```bash

	pnpm run gateway:dev 

	```

	控制台会打印端口（通常 19001），在浏览器打开对应地址（如 `http://localhost:19001`）。

	### 步骤 7：在 Web UI 中测试 

	1. 新建或选择一个 session

	2. 确认当前模型为豆包（模型选择器中选择 Doubao-Seed 2.0 等）

	3. 发送一条简单消息，如「你好」

	### 步骤 8：查看日志排查问题 

	发消息时观察运行 `gateway:dev` 的终端输出，关注：

	- `[DoubaoWebStream] Auth options keys: ...` —— 是否有 `sessionid` 等

	- `[DoubaoWebClient] 发送请求到: ...` —— 请求是否发出

	- `[DoubaoWebClient] 收到 N 个 SSE 事件但未解析出文本` —— 若出现，说明豆包返回格式与解析逻辑不匹配

	- 任何 `Error` 或 `❌` —— 具体错误信息

	---

	## 四、常见失败原因 

	| 现象 | 可能原因 | 处理建议 |

	|------|----------|----------|

	| Web UI 无任何回复 | 1. 认证未配置或 sessionid 失效

2. 模型未选豆包

3. doubao-proxy：代理未启动或 baseUrl 错误 | 重新 onboard、确认模型、检查 doubao-proxy 是否运行 |

	| `No API key found for doubao-web` / `doubao-proxy` | auth-profiles 中无豆包配置 | 重新运行 onboard 并选对应方案 |

	| doubao-proxy 连接失败 | 代理未启动或 baseUrl 配置错误 | 确认 doubao-free-api 在运行，检查 `openclaw.json` 中 baseUrl |

	| `收到 N 个 SSE 事件但未解析出文本` | 仅 doubao-web：豆包 SSE 格式与解析逻辑不符 | 需更新 `doubao-web-client.ts`；或改用 doubao-proxy |

	| `710022004` 或 rate limit | 豆包限流 | 等待 1–2 小时后再试 |

	| 运行的是系统 openclaw | 使用了全局安装的 openclaw | 用 `pnpm run openclaw` 且确保有 `.openclaw-state` 或设置 `OPENCLAW_STATE_DIR` |

	---

	## 五、状态目录说明 

	- **默认**：`~/.openclaw`（与系统全局 openclaw 共用）

	- **项目内**：项目根目录有 `.openclaw-state` 时，`run-node.mjs` 会设置 `OPENCLAW_STATE_DIR`，此时配置和会话都保存在 `.openclaw-state/` 下

	如果你之前用系统 openclaw 配过豆包，而当前用项目运行，需要：

	- 要么在项目内重新 onboard（使用 `.openclaw-state`）

	- 要么把 `~/.openclaw/agents/main/agent/auth-profiles.json` 中豆包相关条目复制到 `.openclaw-state/agents/main/agent/auth-profiles.json`

######################

仅限技术交流，如有侵权请联系删除

业务实施流程

需求调研 →

团队组建和动员 →

数据初始化 →

调试完善 →

解决方案和选型 →

硬件网络部署 →

系统部署试运行 →

系统正式上线 →

合作协议

系统开发/整合

制作文档和员工培训

售后服务

马上咨询： 如果您有业务方面的问题或者需求，欢迎您咨询！我们带来的不仅仅是技术，还有行业经验积累。
QQ: 39764417/308460098 Phone: 13 9800 1 9844 / 135 6887 9550 联系人：石先生/雷先生