reader/docs/openclaw/openclaw-handoff.md

OpenClaw Handoff

Purpose

This repository provides a FreshRSS-first reading pipeline for OpenClaw:

FreshRSS unread items -> RSS content extraction -> LLM summary -> rule engine -> OpenClaw delivery payload

OpenClaw should treat this repository as an MCP-backed upstream content processor.

Production Entrypoint

OpenClaw should call the MCP tool:

• run_freshrss_openclaw_pipeline

This is the canonical entrypoint for production use.

Required Environment Variables

The MCP server process must have these variables available:

• FRESHRSS_API_BASE_URL
• FRESHRSS_USERNAME
• FRESHRSS_API_PASSWORD
• LLM_API_URL
• LLM_API_KEY
• LLM_MODEL

Example:

set FRESHRSS_API_BASE_URL=http://127.0.0.1:8081/api/greader.php
set FRESHRSS_USERNAME=osiman
set FRESHRSS_API_PASSWORD=your-api-password
set LLM_API_URL=https://api.deepseek.com
set LLM_API_KEY=your-llm-api-key
set LLM_MODEL=deepseek-chat

Server Startup

Install dependencies:

pip install -e .

Start the MCP server:

summary-mcp

Recommended MCP Call

Recommended default call:

{
  "limit": 5,
  "mark_read": false,
  "include_read": false,
  "debug_artifacts": false,
  "timeout_seconds": 60,
  "max_retries": 2
}

Recommended semantics:

• Use mark_read=false while validating integration.
• Use mark_read=true only after confirming OpenClaw will consume the returned payload successfully.
• Keep debug_artifacts=false for routine production runs.
• Set debug_artifacts=true only when troubleshooting a bad batch.

What The Tool Returns

Primary return fields:

• run_id
• output_dir
• raw_output
• delivery_output
• report_output
• pulled_count
• delivered_count
• marked_read_count
• status_counts
• delivery_payload
• keyword_index

Optional:

• items
  • Returned only when include_item_reports=true

Minimal Output Files

By default the pipeline writes only:

• outputs/freshrss/rerun/<run_id>/raw/freshrss.raw.json
• outputs/freshrss/rerun/<run_id>/candidates/openclaw-delivery-payload.json
• outputs/freshrss/rerun/<run_id>/run-report.json

It also updates local runtime keyword data:

• data/term_index/daily/YYYY-MM-DD.json
• data/term_index/term_stats.json

If debug_artifacts=true, the pipeline additionally writes per-item intermediate files.

Payload Specs

OpenClaw payload field specs live here:

• docs/openclaw/openclaw-candidate-input-field-spec.md
• docs/openclaw/openclaw-delivery-payload-spec.md

Read-State Semantics

The pipeline reads from FreshRSS unread items by default.

If mark_read=true:

• items are marked as read only after the final openclaw-delivery-payload.json has been written successfully
• only successfully delivered items are marked as read
• failed or skipped items remain unread

FreshRSS Content Policy

For FreshRSS items, the pipeline is RSS-first and does not re-crawl webpages.

Behavior:

• use item.raw_content first
• if missing, use item.raw_summary
• if neither contains usable content, skip the item
• do not fetch the original webpage again for FreshRSS items

This is intentional.

Keyword Cleanup Governance

This repository also includes a lightweight keyword-governance flow for downstream review.

Current pieces:

• runtime keyword stats
  • data/term_index/daily/YYYY-MM-DD.json
  • data/term_index/term_stats.json
• governance config
  • configs/term_cleanup_policy.json
  • configs/term_watchlist.json
  • configs/term_change_log.json
• review bundle builder
  • skills/keyword-cleanup-review/scripts/build_review_bundle.py
• accepted-suggestion writer
  • scripts/apply_term_suggestions.py

Current status:

• OpenClaw can read the keyword review bundle as maintenance input
• accepted suggestions still require explicit human confirmation
• the repository can write accepted watch / alias / stopword / interest-keyword changes after confirmation
• this governance flow is not yet wired into a periodic scheduler inside the repository

Boundary:

• keyword cleanup is a maintenance flow, not the production RSS ingestion path
• the repository does not auto-apply cleanup suggestions without confirmation
• current keyword stats are built from the delivered candidate payload, not yet from a final DailyDigest

Known Limitations

• Some sources put only partial content in RSS; those items may be skipped if RSS content is insufficient.
• WeChat articles often block direct crawling, but this pipeline now avoids that path for FreshRSS items and uses RSS-provided content when available.
• Rule behavior is still conservative in some cases; many items may land in review depending on current rules.
• Paywall heuristics may produce false positives for some Chinese text patterns.
• Keyword cleanup governance is usable now, but periodic scheduling and before/after evaluation are not implemented yet.

Files OpenClaw Should Read First

Recommended reading order for a new maintainer:

1. README.md
2. docs/openclaw/openclaw-handoff.md
3. docs/openclaw/openclaw-candidate-input-field-spec.md
4. docs/openclaw/openclaw-delivery-payload-spec.md
5. docs/design/daily-keyword-index-design.md
6. skills/keyword-cleanup-review/SKILL.md
7. docs/current/context-reset-brief.md

Current Recommendation

For integration handoff, the repository is usable now.

The minimum you need to give OpenClaw is:

• the repository code
• the MCP server startup command
• the required environment variables in the target environment
• the instruction to call run_freshrss_openclaw_pipeline

If OpenClaw will also participate in keyword-governance review, additionally point it to:

• docs/design/daily-keyword-index-design.md
• skills/keyword-cleanup-review/SKILL.md
• scripts/apply_term_suggestions.py