# Facebook AI Operator 安装部署指南

这份文档面向客户交付、试点部署和本地私有化安装。推荐部署形态是：

```text
客户本机 / 私有服务器
  -> Facebook-auto Web 控制台
  -> OpenClaw MCP 工具
  -> 本机 Chrome CDP 执行器
  -> 客户自己登录的 Facebook
```

系统不保存 Facebook 账号密码，不绕过验证码、登录态、权限或平台风控。发布、私信、加好友等高影响动作建议默认人工确认。

## 一、环境要求

### 必需

- macOS 或 Linux 开发环境
- Node.js 20+
- npm
- Chrome 浏览器
- 可登录 Facebook 的客户账号
- OpenClaw 已安装并可启动

### 推荐

- 独立的客户电脑或云桌面
- 稳定网络
- 专门的 Chrome 用户数据目录
- 每个客户单独一份项目目录和 `data/db.json`

## 二、首次安装

进入项目目录：

```bash
cd /Users/momo/Project/Facebook-auto
```

安装依赖：

```bash
npm install
```

复制环境变量模板：

```bash
cp .env.example .env
```

至少确认 `.env` 里有：

```bash
OPENCLAW_SHARED_TOKEN=replace-with-a-long-random-token
FACEBOOK_AUTO_PROGRESS_NOTIFY=true
FACEBOOK_AUTO_FRIEND_DAILY_LIMIT=12
FACEBOOK_AUTO_PUBLISH_DAILY_LIMIT=8
```

如果要使用 AI 客服草稿和 AI 分析，配置：

```bash
OPENAI_API_KEY=replace-with-openai-compatible-key
OPENAI_BASE_URL=https://api.openai.com
OPENAI_MODEL=gpt-4o-mini
```

## 三、启动项目

普通启动：

```bash
npm run dev
```

打开控制台：

```text
http://localhost:3000
```

客户交付时建议先打开：

```text
http://localhost:3000/?tab=setup
```

按“初始化向导”逐项完成授权、Chrome、Facebook、OpenClaw、知识库和回归检查。

## 四、启动可接管 Chrome

如果要让主代码控制当前 Chrome，Chrome 必须带远程调试端口启动。

推荐方式：

```bash
npm run chrome:debug:current
npm run dev
```

如果脚本提示普通 Chrome 已经打开，请先手动退出 Chrome：

```text
Cmd + Q
```

然后重新运行：

```bash
npm run chrome:debug:current
```

如果当前日常 Chrome 无法复用，使用专用调试环境：

```bash
npm run dev:facebook:debug
```

第一次使用专用环境时，需要在打开的 Chrome 里登录 Facebook 一次。

## 五、注册 OpenClaw MCP

注册 MCP 工具：

```bash
npm run openclaw:register-mcp
```

同步 OpenClaw skill：

```bash
npm run openclaw:sync-skill
```

启动带 token 的 OpenClaw 会话：

```bash
bash scripts/openclaw-facebook-chat.sh
```

在 OpenClaw 中先运行：

```text
使用 facebook-auto-ops skill。先调用 facebook_auto_setup_status、facebook_auto_health 和 facebook_auto_summary，不要做写操作。
```

如果检查通过，再开始创建商机发现、客服草稿或内容任务。

## 六、初始化向导验收

打开：

```text
http://localhost:3000/?tab=setup
```

检查项：

1. 授权与套餐  
   确认客户名称、套餐、授权状态、到期日期正确。

2. Chrome 执行器  
   必须显示 CDP 可用。

3. Facebook 登录态  
   在可接管 Chrome 中登录 Facebook 后，点击“标记 Facebook 已连接”。

4. OpenClaw 互通  
   确认 `OPENCLAW_SHARED_TOKEN` 已配置，MCP 工具可调用。

5. 知识库  
   导入产品、价格、物流、FAQ。否则客服草稿只能做低置信度回复。

6. 线索回归  
   点击“运行线索回归”，应显示帖子、小组、Reels、Marketplace 样本通过。

## 七、商用套餐与风控

打开：

```text
http://localhost:3000/?tab=ops
```

商用工作台会显示：

- 当前套餐
- 授权状态
- 到期时间
- 今日商机发现额度
- 今日发布额度
- 今日加好友额度
- 今日客服回复额度
- 操作审计记录

### 一次性采购离线授权

离线授权不需要先搭服务器，适合“买断/一次性采购”交付：

1. 你在自己的卖方机器生成一对 Ed25519 密钥。
2. 客户在初始化向导中复制“本机机器码”。
3. 你用私钥给客户机器码签发 `license.json`。
4. 客户导入 `license.json`。
5. 软件本地用公钥验签，确认套餐、机器码、到期时间和额度。

生成密钥：

```bash
npm run license:keygen
```

这会生成：

```text
license-keys/private.pem
license-keys/public.pem
```

`private.pem` 只放在你自己的卖方电脑，不要发给客户。客户部署包只需要公钥，配置方式二选一：

```bash
FACEBOOK_AUTO_LICENSE_PUBLIC_KEY_PATH=license-keys/public.pem
```

或把公钥内容写入：

```bash
FACEBOOK_AUTO_LICENSE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
```

客户复制机器码后，你生成一次性授权：

```bash
npm run license:generate -- \
  --customer "ABC Trading" \
  --machine-id "客户初始化向导显示的机器码" \
  --plan growth \
  --purchase-type one_time \
  --expires-at 2099-12-31 \
  --support-expires-at 2027-05-23 \
  --daily-lead-searches 30 \
  --daily-publishes 5 \
  --daily-friend-requests 30 \
  --daily-messenger-replies 60
```

生成的 `licenses/*.license.json` 发给客户导入即可。一次性采购建议把 `expiresAt` 设置到长期日期，把 `supportExpiresAt` 当作升级/维护服务到期日；核心功能按 `expiresAt` 控制，维护服务到期不影响已购功能。

读取当前授权：

```bash
curl -s http://127.0.0.1:3000/api/commercial/license
```

读取本机机器码：

```bash
curl -s http://127.0.0.1:3000/api/commercial/machine-id
```

诊断授权状态：

```bash
curl -s http://127.0.0.1:3000/api/commercial/license/diagnose
```

导入离线授权可以在初始化向导页面完成，也可以调用：

```bash
curl -s -X POST http://127.0.0.1:3000/api/commercial/license/import \
  -H "content-type: application/json" \
  -d '{"license": {"payload": {}, "signature": "..."}}'
```

试用配置仍可临时更新：

```bash
curl -s -X POST http://127.0.0.1:3000/api/commercial/license \
  -H "content-type: application/json" \
  -d '{
    "customerName": "Demo Customer",
    "plan": "growth",
    "status": "active",
    "expiresAt": "2026-12-31"
  }'
```

关键写动作会先检查授权和今日额度：

- 商机发现
- 内容发布
- 加好友任务
- Messenger 回复任务

## 八、知识库配置

通过 OpenClaw 工具：

```text
使用 facebook-auto-ops skill。调用 facebook_auto_upsert_knowledge_document，保存我的产品介绍、价格、物流、FAQ。
```

也可以直接调用 API：

```bash
curl -s -X POST http://127.0.0.1:3000/api/knowledge \
  -H "content-type: application/json" \
  -d '{
    "title": "产品 FAQ",
    "source": "manual",
    "content": "这里填写产品、价格、物流、售后、常见问题。"
  }'
```

## 九、常用验收指令

### 安装状态

```text
使用 facebook-auto-ops skill。调用 facebook_auto_setup_status，列出未完成项和下一步。
```

### 浏览器健康

```text
使用 facebook-auto-ops skill。调用 facebook_auto_health，检查 Chrome CDP、Facebook tab 和 OpenClaw 互通。
```

### 商机回归

```text
使用 facebook-auto-ops skill。运行 facebook_auto_run_lead_fixture_regression，总结帖子、小组、Reels、Marketplace 样本是否通过。
```

### 安全发帖

```text
使用 facebook-auto-ops skill。先运行 diagnose_feed_post。入口可用后创建发帖草稿，autoPublish=false，没有我确认不要发布。
```

### 商机发现

```text
使用 facebook-auto-ops skill。用 Disposable Ice Pop Bags 创建 lead search，searchType=all，deepComments=true，完成后总结高意向评论人和来源证据，不要自动加好友。
```

## 十、备份与迁移

备份建议保留：

- `app/`
- `lib/`
- `mcp/`
- `openclaw/`
- `docs/`
- `scripts/`
- `data/db.json`
- `.env`
- `package.json`
- `package-lock.json`

可排除：

- `node_modules/`
- `.next/`
- `.next-dev/`
- `.next-verify/`

示例：

```bash
mkdir -p backups
tar --exclude='./node_modules' \
  --exclude='./.next' \
  --exclude='./.next-dev' \
  --exclude='./.next-verify' \
  -czf backups/facebook-ai-operator-backup-$(date +%Y%m%d-%H%M%S).tgz .
```

迁移到新机器后：

```bash
npm install
npm run openclaw:register-mcp
npm run openclaw:sync-skill
npm run chrome:debug:current
npm run dev
```

## 十一、常见问题

### 1. Chrome CDP 不可用

先退出普通 Chrome，再运行：

```bash
npm run chrome:debug:current
```

### 2. OpenClaw 说看不到 Facebook

不要让 OpenClaw 根据桌面截图判断。让它调用：

```text
facebook_auto_health
facebook_auto_setup_status
```

以返回的 CDP/Facebook tab 状态为准。

### 3. 可以登录 Facebook 但任务不执行

检查：

- Chrome 是否带 `9222` 调试端口
- `http://localhost:3000/?tab=setup` 是否显示 Chrome 执行器完成
- 任务是否处于人工确认状态
- 商用工作台是否超过今日额度

### 4. 客服回复质量低

通常是知识库为空或内容太少。先导入：

- 产品说明
- 价格规则
- MOQ
- 发货地区
- 物流时效
- 售后政策
- 常见问题

### 5. 线索结果不准确

先运行：

```text
facebook_auto_run_lead_fixture_regression
```

如果离线回归通过，再检查真实 Facebook 页面是否评论受限、未展开、排序不对或当前账号权限不足。
