# OpenClaw Integration

This project can interoperate with OpenClaw in both directions without modifying `~/.openclaw` internals.

## Direction 1: OpenClaw -> Facebook-auto

### Recommended: MCP tools

For command-and-control use, register the project as an OpenClaw MCP server. This makes the local app show up as typed tools inside OpenClaw, so OpenClaw can call `facebook_auto_create_lead_search`, `facebook_auto_queue_collect_comments`, `facebook_auto_pending`, and similar tools directly instead of manually composing `curl` commands.

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

The registration script reads `OPENCLAW_SHARED_TOKEN` from `.env` and writes one OpenClaw MCP entry named `facebook-auto`. It passes these env vars to the MCP server:

```bash
FACEBOOK_AUTO_BASE_URL=http://127.0.0.1:3000
FACEBOOK_AUTO_TOKEN=replace-with-openclaw-shared-token
```

After registration, start the local app and use OpenClaw normally:

```bash
npm run dev:facebook
openclaw chat
```

For extension-free operation, run the app with a CDP-enabled Chrome and keep Facebook logged in there:

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

If Chrome is already open without `--remote-debugging-port`, quit Chrome manually first and run `npm run chrome:debug:current` again. A normal already-open Chrome process cannot be attached by the main app after the fact.

The default OpenClaw path is now:

```text
Upstream command source -> OpenClaw -> facebook-auto MCP -> Next.js API -> browser/CDP executor -> logged-in Chrome -> Facebook
```

The upstream command source can be WeChat, OpenClaw Web UI, OpenClaw CLI, or another bridge. It is intentionally out of scope for this project. OpenClaw should judge readiness from `facebook_auto_health`, especially `health.browser`, not from screenshots, visible desktop state, or how the user delivered the command.

Browser executor safety defaults:

- progress notifications to OpenClaw: `FACEBOOK_AUTO_PROGRESS_NOTIFY`, default `true`
- daily friend-request limit: `FACEBOOK_AUTO_FRIEND_DAILY_LIMIT`, default `12`
- daily auto-publish limit: `FACEBOOK_AUTO_PUBLISH_DAILY_LIMIT`, default `8`
- friend-request random delay: `FACEBOOK_AUTO_FRIEND_DELAY_MIN_MS` to `FACEBOOK_AUTO_FRIEND_DELAY_MAX_MS`, default `8000-25000`
- failed browser tasks save screenshots and metadata under `/executor-evidence/*`

Then ask OpenClaw things like:

```text
查看 Facebook-auto 待处理事项
用 Disposable Ice Pop Bags 搜索商机，最多访问 5 个帖子并深度采评论
用 Disposable Ice Pop Bags 搜索商机，采集评论人，AI 分数 75 以上自动保存并最多加 8 个好友
先对当前 Facebook 帖子运行 browser snapshot，确认评论排序和展开按钮是否可见
把这个 Facebook 帖子加入评论采集队列：https://www.facebook.com/groups/.../permalink/...
```

Available MCP tools are served by:

- [mcp/facebook-auto-server.mjs](/Users/momo/Project/Facebook-auto/mcp/facebook-auto-server.mjs)

Current tool surface:

- `facebook_auto_health`
- `facebook_auto_summary`
- `facebook_auto_pending`
- `facebook_auto_action`
- `facebook_auto_create_daily_plan`
- `facebook_auto_run_operator_plan`
- `facebook_auto_create_lead_search`
- `facebook_auto_create_lead_discovery_run`
- `facebook_auto_analyze_lead_table`
- `facebook_auto_export_lead_table`
- `facebook_auto_upsert_knowledge_document`
- `facebook_auto_queue_collect_comments`
- `facebook_auto_browser_snapshot`
- `facebook_auto_check_facebook_login`
- `facebook_auto_check_publish_readiness`
- `facebook_auto_queue_publish_dry_run`
- `facebook_auto_queue_send_friend_request`
- `facebook_auto_diagnose_feed_post`
- `facebook_auto_diagnose_group_post`
- `facebook_auto_queue_publish_feed_post`
- `facebook_auto_queue_publish_group_post`
- `facebook_auto_queue_send_messenger_reply`
- `facebook_auto_approve_messenger_reply`
- `facebook_auto_ignore_messenger_message`
- `facebook_auto_save_crm_lead`
- `facebook_auto_set_crm_lead_status`
- `facebook_auto_run_browser_executor`
- `facebook_auto_run_smoke_regression`
- `facebook_auto_run_lead_fixture_regression`

### Fallback: protected HTTP endpoints

Use the protected integration endpoints:

- `GET /api/integrations/openclaw/health`
  - `health.browser.facebookPageState.pageType` tells OpenClaw whether the current Facebook tab is `home_feed`, `search_posts`, `group_post`, `reel`, `marketplace_search`, etc.
  - Treat `home_feed` as suitable for login checks and feed publishing, not as a lead-collection source.
  - For keyword lead discovery, ask Facebook-auto to navigate through search channels instead of scraping the visible home feed.
  - Use `queue_collect_comments` only with concrete post, group-post, Reel, or video URLs; use `create_lead_search` for search pages and Marketplace discovery.
- `GET /api/integrations/openclaw/summary`
- `GET /api/integrations/openclaw/pending`
- `POST /api/integrations/openclaw/action`

All requests require:

- `Authorization: Bearer <OPENCLAW_SHARED_TOKEN>`
  or
- `x-openclaw-token: <OPENCLAW_SHARED_TOKEN>`

Recommended env vars for the caller:

```bash
FACEBOOK_AUTO_BASE_URL=http://127.0.0.1:3000
FACEBOOK_AUTO_TOKEN=replace-with-openclaw-shared-token
```

Quick local launcher for the HTTP/skill fallback:

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

Prepare Facebook runtime first:

```bash
bash scripts/prepare-facebook-runtime.sh
```

Prepare runtime and launch OpenClaw in one go:

```bash
bash scripts/prepare-facebook-runtime.sh && bash scripts/openclaw-facebook-chat.sh
```

If you want to open Facebook inside your normal logged-in Chrome profile instead of the dedicated debug profile, use:

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

If you need Playwright / CDP mode, use:

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

This wrapper reads `OPENCLAW_SHARED_TOKEN` from the local `.env` and exports:

- `FACEBOOK_AUTO_BASE_URL`
- `FACEBOOK_AUTO_TOKEN`

## Direction 2: Facebook-auto -> OpenClaw

`Facebook-auto` can notify a running OpenClaw gateway using OpenClaw webhook hooks.

OpenClaw documents webhook hooks under Scheduled Tasks:

- `POST /hooks/wake`
- `POST /hooks/agent`

Reference:

- https://docs.openclaw.ai/automation/cron-jobs

Recommended env vars in `Facebook-auto`:

```bash
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_HOOK_TOKEN=replace-with-openclaw-hook-token
OPENCLAW_HOOK_MODE=agent
OPENCLAW_HOOK_PATH=/hooks/agent
OPENCLAW_AGENT_ID=main
OPENCLAW_AGENT_TIMEOUT_SECONDS=120
```

Notes:

- OpenClaw webhook hooks must be enabled on the OpenClaw side.
- Use a dedicated hook token.
- Do not reuse the gateway auth token as the hook token.

## Event sources

`Facebook-auto` currently sends best-effort OpenClaw notifications for:

- new Messenger messages pending review
- completed lead-search analysis
- failed lead searches
- failed browser/CDP tasks

Notifications never block the main Facebook-auto workflow.

For CLI fallback mode, Facebook-auto automatically injects `FACEBOOK_AUTO_BASE_URL` and `FACEBOOK_AUTO_TOKEN` when it runs `openclaw agent`, so event-triggered OpenClaw sessions can call the protected integration APIs without additional manual setup.

## Skill pack

A ready-to-install skill template lives at:

- [openclaw/facebook-auto-ops/SKILL.md](/Users/momo/Project/Facebook-auto/openclaw/facebook-auto-ops/SKILL.md)

It teaches OpenClaw to use the safe integration endpoints instead of reading project internals directly.

After updating the project skill, sync it into the active OpenClaw workspace:

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