reader/docs/openclaw/openclaw-handoff.md

OpenClaw Handoff

Role

This file is the integration overview for OpenClaw maintainers.

Use it for:

• reader capability boundary
• production MCP entrypoints
• environment requirements
• integration rules and limitations

Do not use it as the step-by-step runbook. For formal orchestration, read docs/openclaw/openclaw-orchestration-flow.md. For field contracts, read:

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

Historical plans and incident documents live under docs/openclaw/archive/.

Purpose

reader is the upstream FreshRSS processing service for OpenClaw:

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

reader is responsible for:

• FreshRSS pull
• content extraction
• LLM summary generation and validation
• rule-based filtering
• OpenClaw delivery payload generation
• run-state persistence and run/result lookup
• async resume control for the FreshRSS workflow
• async selected-article summary generation from existing extracted files

reader is not responsible for:

• Hugo publishing
• chat reporting
• user confirmation handling
• IMA upload orchestration

Production Surface

Current MCP tool count: 21.

Main daily workflow:

• start_freshrss_pipeline_job
• get_freshrss_pipeline_job_status
• get_freshrss_pipeline_job_result
• get_run_status
• list_runs
• list_run_artifacts
• get_delivery_payload
• get_run_report

Resume workflow:

• inspect_resume_plan
• start_resume_job
• get_resume_job_status
• get_resume_job_result
• resume_run

Selected-article summary workflow:

• start_article_summary_job
• get_article_summary_job_status
• get_article_summary_job_result
• generate_article_summaries

Debug / single-step tools:

• run_freshrss_openclaw_pipeline
• extract_url_content
• extract_item_content
• filter_summary_result

Production rules:

• main production start path is start_freshrss_pipeline_job
• production resume path is inspect_resume_plan -> start_resume_job -> get_resume_job_status -> get_resume_job_result
• run_freshrss_openclaw_pipeline is sync debug / fallback only
• resume_run is sync debug / fallback only
• generate_article_summaries is sync debug / fallback only

Production Contract

OpenClaw should treat the returned run_id from get_freshrss_pipeline_job_result as the only stable handle for follow-up reads.

OpenClaw should not hand-build these paths:

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

If filesystem access is needed for debugging, only consume paths returned by MCP:

• output_dir
• artifact.path
• delivery_output
• report_output

Top-level status is the only status field callers should branch on. status_source and state_conflict are explanatory fields for reconciled status.

Minimal Production Sequence

Daily workflow:

1. Call start_freshrss_pipeline_job
2. Poll get_freshrss_pipeline_job_status
3. On success, read get_freshrss_pipeline_job_result
4. Persist the returned run_id
5. Use get_run_status, get_delivery_payload, and get_run_report for follow-up reads

Resume workflow:

1. Call inspect_resume_plan(run_id)
2. Only if can_resume=true and recommended_action=resume, call start_resume_job
3. Poll get_resume_job_status
4. Read get_resume_job_result

Selected-article summary workflow:

1. Call start_article_summary_job with a real extracted file path and non-empty selected_ids
2. Poll get_article_summary_job_status
3. Read get_article_summary_job_result

Capability Boundary

Formal workflow boundary:

• only workflow freshrss_daily_digest
• every current FreshRSS run writes run-state.json
• get_run_status / list_runs / list_run_artifacts can still infer basic state for older runs without run-state.json
• resume requires a valid run-state.json; inferred historical runs are not resumable

Resume boundary:

• resume in place on the original run_id
• supported resume points:
  • generate_summaries
  • apply_filters
  • build_delivery_payload
  • write_run_report
• unsupported resume points:
  • fetch_feed
  • extract_articles
• production resume prefers:
  • summary/summary-batch.json
  • candidates/candidate-batch.json
• if required artifacts are missing, recovery should return non-resumable instead of silently falling back

Selected-article summary boundary:

• uses existing extracted files as input
• should not re-fetch original URLs

Output Expectations

Main daily pipeline core artifacts:

• outputs/freshrss/rerun/<run_dir>/run-state.json
• outputs/freshrss/rerun/<run_dir>/raw/freshrss.raw.json
• outputs/freshrss/rerun/<run_dir>/summary/summary-batch.json
• outputs/freshrss/rerun/<run_dir>/candidates/candidate-batch.json
• outputs/freshrss/rerun/<run_dir>/candidates/openclaw-delivery-payload.json
• outputs/freshrss/rerun/<run_dir>/candidates/digest-brief.json
• outputs/freshrss/rerun/<run_dir>/run-report.json
• outputs/freshrss/rerun/<run_dir>/extracted/item-XX.extracted.json

Async job state directories:

• main pipeline job: outputs/freshrss/pipeline_jobs/<job_id>/
• resume job: outputs/freshrss/resume_jobs/<job_id>/
• article-summary job: outputs/freshrss/article_summary_jobs/<job_id>/

Each job directory minimally contains:

• run-state.json
• input.json
• result.json on success
• job-report.json

Environment And Startup

Required environment variables:

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

Startup:

pip install -e .
summary-mcp

Recommended production start call:

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

Data And Content Policy

FreshRSS processing is RSS-first:

• 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

Read-state policy:

• items are marked read only after successful delivery payload write
• only successfully delivered items are marked read

Downstream boundary:

• the daily digest goes to Hugo and chat reporting
• the full daily digest should not be uploaded to IMA
• only explicitly user-selected article summaries should be uploaded to IMA

Related Maintenance Flow

Keyword cleanup exists as a separate maintenance flow, not the main RSS ingestion path.

Relevant files:

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

Known Limitations

• some sources expose only partial RSS content; those items may be skipped
• rule behavior is still conservative; many items may land in review
• paywall heuristics may still produce false positives on some Chinese text
• keyword cleanup governance is usable but not yet wired to periodic scheduling

Read First

Recommended reading order for a new maintainer:

1. README.md
2. docs/openclaw/README.md
3. docs/openclaw/openclaw-handoff.md
4. docs/openclaw/openclaw-orchestration-flow.md
5. docs/openclaw/openclaw-candidate-input-field-spec.md
6. docs/openclaw/openclaw-delivery-payload-spec.md
7. docs/current/context-reset-brief.md