Open-source SEO, GEO, and marketing skills for AI agents.
Improve OpenClaw SEO operator setup
Tong Chenf9f7ffc8a9c1
diff --git a/openclaw/README.md b/openclaw/README.mdindex 5f5ac394..725f6d50 100644--- a/openclaw/README.md+++ b/openclaw/README.md@@ -56,7 +56,7 @@ export TOPRANK_OPENCLAW_HOME=/custom/path## Install-The wrappers are designed to be **symlinked** into `~/.openclaw/skills/` so they can still resolve the canonical `seo/` skills in this repo.+Run from the Toprank repo root:```bash./openclaw/install/install.sh@@ -66,7 +66,68 @@ That script:1. creates `~/.toprank/openclaw/` if needed,2. bootstraps `portfolio.json` and `schedule.json`,-3. symlinks all `openclaw/skills/*` into `~/.openclaw/skills/`.+3. copies all OpenClaw wrapper skills into `~/.openclaw/skills/`,+4. links support paths so the wrappers can still resolve this repo's canonical `seo/` skills.++Why copy instead of symlink wrapper skills directly? OpenClaw skill discovery intentionally rejects symlinks that escape the configured skill root. The installer copies wrappers into the OpenClaw skill root and uses stable support links for repo-relative files.++Verify:++```bash+openclaw skills check | grep -i toprank+python3 -m pytest -q openclaw/tests+```++## Paste this into OpenClaw++Use this as the setup prompt for a fresh machine or a new OpenClaw instance. Replace the placeholders before pasting.++```text+Set up the Toprank OpenClaw SEO Operator on this machine.++Repo:+- If the Toprank repo already exists locally, use it; do not reclone.+- Otherwise clone https://github.com/nowork-studio/toprank and cd into the repo root.++Install:+1. Run: ./openclaw/install/install.sh+2. Verify Toprank skills are discoverable: openclaw skills check | grep -i toprank+3. Run tests: python3 -m pytest -q openclaw/tests++Sites:+- Register these sites if they are not already in ~/.toprank/openclaw/portfolio.json:+ - <site_id_1> with GSC property <gsc_property_1>+ - <site_id_2> with GSC property <gsc_property_2>+- If GSC properties are unknown, run:+ python3 seo/seo-analysis/scripts/list_gsc_sites.py+ Then update each site's ~/.toprank/openclaw/sites/<site_id>/site-profile.json with "gsc_property".++Background wiring:+- Install OpenClaw cron jobs with:+ ./openclaw/install/install-openclaw-cron.sh --to "<delivery_destination>" --channel "<channel>" --thread-id "<optional_thread_id>"+- If there is no chat delivery target, omit --to; the jobs should be installed with --no-deliver.+- Do not pass --model unless you first verify the model is accepted by this OpenClaw instance's model allowlist.++Smoke test:+1. Run the scheduler once:+ TOPRANK_OPENCLAW_HOME="$HOME/.toprank/openclaw" python3 openclaw/bin/run_scheduler.py+2. Run one weekly review:+ TOPRANK_OPENCLAW_HOME="$HOME/.toprank/openclaw" python3 openclaw/bin/weekly_review.py "<site_id_1>"+3. Confirm the review wrote audit.json, action-plan.json, and verification.json under ~/.toprank/openclaw/sites/<site_id>/runs/.+4. Confirm openclaw cron list shows Toprank OpenClaw Scheduler and one Toprank Weekly Review job per active site.++Policy:+- This is an SEO operator loop, not an auto-publisher.+- Do not edit websites, CMS content, repos, or publish changes without explicit approval.+- Weekly review jobs may propose actions and write artifacts only.++Report back with:+- installed skill names,+- active sites and GSC properties,+- cron job ids/schedules,+- smoke-test artifact path,+- any blockers.+```## Bootstrap a site work folder@@ -186,7 +247,27 @@ What it does today:- updates `learned-patterns.json` with outcome priors,- surfaces unsupported due items as `ready_for_attention`.-Install it on macOS with launchd:+Install it with OpenClaw cron:++```bash+# With chat delivery for useful weekly-review summaries:+./openclaw/install/install-openclaw-cron.sh \+ --to "<delivery_destination>" \+ --channel telegram \+ --thread-id "<optional_thread_id>"++# Without chat delivery:+./openclaw/install/install-openclaw-cron.sh+```++The OpenClaw cron installer creates:++- `Toprank OpenClaw Scheduler` — hourly follow-up processor+- `Toprank Weekly Review — <site>` — one weekly review per active portfolio site++It intentionally does not set a model by default. If you want a model override, pass `--model <provider/model>` only after confirming the local OpenClaw model allowlist accepts it.++macOS `launchd` is still available as a lower-level alternative:```bash./openclaw/install/install-launchd.sh --write-only@@ -194,7 +275,7 @@ Install it on macOS with launchd:./openclaw/install/install-launchd.sh```-Or use the cron example at `openclaw/install/toprank-openclaw.cron.example`.+Or use the system cron example at `openclaw/install/toprank-openclaw.cron.example`.This is now the core of a real autonomous operator loop.diff --git a/openclaw/bin/weekly_review.py b/openclaw/bin/weekly_review.pyindex 257e55a2..cf063bd0 100755--- a/openclaw/bin/weekly_review.py+++ b/openclaw/bin/weekly_review.py@@ -210,6 +210,14 @@ def build_payload(site_id: str, analysis: dict[str, Any], learned: dict[str, Anybase_priority=0.3,)]+ top_issues = [+ {+ **issue,+ "priority_score": issue.get("priority_score", round(issue.get("base_priority", 0.3), 3)),+ "learned_multiplier": issue.get("learned_multiplier", 1.0),+ }+ for issue in top_issues+ ]summary = analysis.get("summary") or {}non_brand_clicks = metrics.get(primary_metric)diff --git a/openclaw/install/install-openclaw-cron.sh b/openclaw/install/install-openclaw-cron.shnew file mode 100755index 00000000..902f5474--- /dev/null+++ b/openclaw/install/install-openclaw-cron.sh@@ -0,0 +1,172 @@+#!/usr/bin/env bash+set -euo pipefail++usage() {+ cat <<'USAGE'+Install OpenClaw cron wiring for the Toprank OpenClaw SEO Operator.++Usage:+ ./openclaw/install/install-openclaw-cron.sh [options]++Options:+ --to <dest> Delivery destination, e.g. Telegram chat id. If omitted, jobs use --no-deliver.+ --channel <channel> Delivery channel for --to. Default: telegram.+ --thread-id <id> Optional Telegram forum topic/thread id.+ --account <id> Optional channel account id.+ --model <model> Optional OpenClaw model override. Omit unless you know the allowlist accepts it.+ --timezone <tz> Cron timezone. Default: America/Los_Angeles.+ --weekly-time <HH:MM> Local time for weekly reviews. Default: 06:30.+ --scheduler-every <dur> Scheduler interval. Default: 1h.+ --sites <csv> Comma-separated sites. Default: active sites from ~/.toprank/openclaw/portfolio.json.+ --runtime-home <path> Toprank runtime home. Default: ~/.toprank/openclaw.+ --repo-root <path> Toprank repo root. Default: auto-detected from this script.+ -h, --help Show this help.++Examples:+ ./openclaw/install/install-openclaw-cron.sh --to "-1001234567890" --thread-id 28+ ./openclaw/install/install-openclaw-cron.sh --no-deliver is not needed; omit --to instead.+USAGE+}++SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"+RUNTIME_HOME="${TOPRANK_OPENCLAW_HOME:-$HOME/.toprank/openclaw}"+CHANNEL="telegram"+TO=""+THREAD_ID=""+ACCOUNT=""+MODEL=""+TIMEZONE="America/Los_Angeles"+WEEKLY_TIME="06:30"+SCHEDULER_EVERY="1h"+SITES_CSV=""++while [[ $# -gt 0 ]]; do+ case "$1" in+ --to) TO="$2"; shift 2 ;;+ --channel) CHANNEL="$2"; shift 2 ;;+ --thread-id) THREAD_ID="$2"; shift 2 ;;+ --account) ACCOUNT="$2"; shift 2 ;;+ --model) MODEL="$2"; shift 2 ;;+ --timezone|--tz) TIMEZONE="$2"; shift 2 ;;+ --weekly-time) WEEKLY_TIME="$2"; shift 2 ;;+ --scheduler-every) SCHEDULER_EVERY="$2"; shift 2 ;;+ --sites) SITES_CSV="$2"; shift 2 ;;+ --runtime-home) RUNTIME_HOME="$2"; shift 2 ;;+ --repo-root) REPO_ROOT="$2"; shift 2 ;;+ -h|--help) usage; exit 0 ;;+ *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;+ esac+done++if ! command -v openclaw >/dev/null 2>&1; then+ echo "ERROR: openclaw CLI not found in PATH." >&2+ exit 1+fi++if [[ ! -x "$REPO_ROOT/openclaw/bin/run_scheduler.py" ]]; then+ echo "ERROR: Toprank repo root looks wrong: $REPO_ROOT" >&2+ exit 1+fi++if [[ ! "$WEEKLY_TIME" =~ ^([01][0-9]|2[0-3]):[0-5][0-9]$ ]]; then+ echo "ERROR: --weekly-time must be HH:MM, got $WEEKLY_TIME" >&2+ exit 1+fi++minute="${WEEKLY_TIME#*:}"+hour="${WEEKLY_TIME%:*}"+hour="$((10#$hour))"+minute="$((10#$minute))"++delivery_args=()+if [[ -n "$TO" ]]; then+ delivery_args=(--announce --channel "$CHANNEL" --to "$TO" --best-effort-deliver)+ [[ -n "$THREAD_ID" ]] && delivery_args+=(--thread-id "$THREAD_ID")+ [[ -n "$ACCOUNT" ]] && delivery_args+=(--account "$ACCOUNT")+else+ delivery_args=(--no-deliver)+fi++read_sites() {+ if [[ -n "$SITES_CSV" ]]; then+ tr ',' '\n' <<<"$SITES_CSV" | sed 's/^ *//;s/ *$//' | grep -v '^$'+ return 0+ fi+ python3 - "$RUNTIME_HOME/portfolio.json" <<'PY'+import json, sys+from pathlib import Path+path = Path(sys.argv[1]).expanduser()+if not path.exists():+ raise SystemExit(f"portfolio.json not found: {path}")+data = json.loads(path.read_text())+for site in data.get("sites", []):+ site_id = site.get("site_id")+ if site_id and site.get("status", "active") == "active" and site_id != "example.com":+ print(site_id)+PY+}++job_exists() {+ local name="$1"+ openclaw cron list --json 2>/dev/null | python3 -c 'import json, sys; name = sys.argv[1]; data = json.load(sys.stdin); raise SystemExit(0 if any(job.get("name") == name for job in data.get("jobs", [])) else 1)' "$name"+}++add_job_if_missing() {+ local name="$1"+ shift+ if job_exists "$name"; then+ echo "exists: $name"+ return 0+ fi+ openclaw cron add --name "$name" "$@"+}++scheduler_msg="Run the Toprank OpenClaw scheduler. Execute exactly: TOPRANK_OPENCLAW_HOME=\"$RUNTIME_HOME\" python3 \"$REPO_ROOT/openclaw/bin/run_scheduler.py\". Parse the JSON. If processed, manual_attention, and restored_from_queue are all empty, reply exactly NO_REPLY. If any are non-empty, summarize what changed and include any item_id/site_id that needs attention. If the command fails, report the blocker."++scheduler_args=(+ --every "$SCHEDULER_EVERY"+ --session isolated+ --light-context+ --message "$scheduler_msg"+ --tools exec+)+[[ -n "$MODEL" ]] && scheduler_args+=(--model "$MODEL")+scheduler_args+=("${delivery_args[@]}")++add_job_if_missing "Toprank OpenClaw Scheduler" "${scheduler_args[@]}"++sites=()+while IFS= read -r site; do+ sites+=("$site")+done < <(read_sites)+if [[ ${#sites[@]} -eq 0 ]]; then+ echo "No active sites found. Add sites with openclaw/bin/onboard_site.py, or pass --sites." >&2+ exit 1+fi++for i in "${!sites[@]}"; do+ site="${sites[$i]}"+ # Cron day-of-week: 1=Monday. Spread sites across weekdays, then wrap.+ dow=$(( (i % 5) + 1 ))+ cron_expr="$minute $hour * * $dow"+ weekly_msg="Run the automated Toprank weekly SEO review for $site. Execute exactly: TOPRANK_OPENCLAW_HOME=\"$RUNTIME_HOME\" python3 \"$REPO_ROOT/openclaw/bin/weekly_review.py\" \"$site\". Then inspect the generated run_dir from stdout. Summarize the top issue, proposed next action, whether it requires approval, and the artifact path. Do not edit websites, CMS, repos, or publish anything. If the command fails, report the blocker."++ weekly_args=(+ --cron "$cron_expr"+ --tz "$TIMEZONE"+ --exact+ --session isolated+ --light-context+ --message "$weekly_msg"+ --tools exec+ )+ [[ -n "$MODEL" ]] && weekly_args+=(--model "$MODEL")+ weekly_args+=("${delivery_args[@]}")++ add_job_if_missing "Toprank Weekly Review — $site" "${weekly_args[@]}"+done++echo+echo "Installed/verified Toprank OpenClaw cron jobs:"+openclaw cron list | grep -i 'Toprank' || truediff --git a/openclaw/install/install.sh b/openclaw/install/install.shindex 525d9422..d3d62759 100755--- a/openclaw/install/install.sh+++ b/openclaw/install/install.sh@@ -2,17 +2,39 @@set -euo pipefailREPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"-SKILL_TARGET_DIR="${OPENCLAW_SKILLS_DIR:-$HOME/.openclaw/skills}"+OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/.openclaw}"+SKILL_TARGET_DIR="${OPENCLAW_SKILLS_DIR:-$OPENCLAW_HOME/skills}"++link_or_warn() {+ local src="$1"+ local dest="$2"+ if [[ -e "$dest" && ! -L "$dest" ]]; then+ echo "warning: $dest exists and is not a symlink; leaving it unchanged" >&2+ return 0+ fi+ ln -sfn "$src" "$dest"+}mkdir -p "$SKILL_TARGET_DIR"python3 "$REPO_ROOT/openclaw/bin/bootstrap_workspace.py" >/dev/nullfor skill_dir in "$REPO_ROOT"/openclaw/skills/*; doname="$(basename "$skill_dir")"- ln -sfn "$skill_dir" "$SKILL_TARGET_DIR/$name"- echo "linked $name -> $skill_dir"+ target="$SKILL_TARGET_DIR/$name"+ rm -rf "$target"+ mkdir -p "$target"+ cp -R "$skill_dir"/. "$target"/+ echo "copied $name -> $target"done+# OpenClaw skill discovery rejects symlinks that escape ~/.openclaw/skills.+# The wrapper skills are copied above, then their repo-relative support paths are+# preserved with stable links for `{baseDir}/../../shared`, `{baseDir}/../../bin`,+# and `{baseDir}/../../../seo`.+link_or_warn "$REPO_ROOT/openclaw/shared" "$OPENCLAW_HOME/shared"+link_or_warn "$REPO_ROOT/openclaw/bin" "$OPENCLAW_HOME/bin"+link_or_warn "$REPO_ROOT/seo" "$HOME/seo"+echoecho "OpenClaw skills installed."echo "Runtime home: ${TOPRANK_OPENCLAW_HOME:-$HOME/.toprank/openclaw}"