Cyber Girlfriend

SKILL.md

---
name: cyber-girlfriend
description: Build or customize an owner-only proactive companion system with a cyber-girlfriend persona, Markdown private-life context, lightweight relationship memory, and OpenClaw presence cron delivery.
version: 2.1.3
---

# Cyber Girlfriend

Use this skill when the user wants an owner-only proactive companion instead of a purely reactive assistant.

This skill gives the owner:
- proactive companion messages sent on a real schedule
- a core persona in `character-profile.md`
- daily private-life context in `day-schedule.md`
- configurable quiet hours and event-level pacing
- lightweight continuity in `life-log.jsonl`
- optional event media such as photos, audio, or video

## Quick Start

This skill is meant to be set up by an agent, not by hand.

If the user wants the default setup, the simplest path is:

> Help me set up cyber girlfriend.

The agent should then gather the minimum inputs, create or update the local files, wire the default cron jobs, and validate the install before claiming success.

## What The User Needs

For a normal install, the user only needs:
- an OpenClaw runtime
- one working delivery route to the owner
- a few persona and daily-life anchors

The user should not need to:
- hand-write JSON
- hand-write cron payloads
- manually wire runner contracts
- read every reference file before getting started

## Default Setup Shape

The recommended starter setup is:
- one daily schedule builder job that writes `day-schedule.md`
- one `companion-presence` cron that runs a deterministic tick wrapper from an isolated cron session
- 1-4 optional life anchors that are written into `day-schedule.md`

Those anchors are life facts, not guaranteed sends.

## What The Agent Sets Up

The current default active path has two small steps:
- `scripts/companion_presence_tick.py --config <CONFIG>`
- inside that wrapper, `scripts/companion_run.py --stage prepare --mode heartbeat --no-record-pending`

The wrapper reads local state through the prepare runner and exits quietly when no current event should send. Only when prepare returns `status = "ok"` does it start the stable companion session with the prepared contract. If the matched event asks for media, text sends first, state commits after text delivery, and media finishes asynchronously. The OpenClaw media completion event returns to that same stable companion session; that completion turn only sends the media.

The default local files are:
- `character-profile.md`
- `day-schedule.md`
- `companion-state.json`
- `life-log.jsonl`

Legacy 1.x inputs such as `persona`, `month-plan.json`, `day-context.json`, and the old multi-slot cron path are upgrade-only compatibility inputs, not the default product path.

## Hard Rules

- Never hardcode secrets.
- Keep proactive behavior owner-only unless the user explicitly wants broader scope.
- Keep runtime-specific values in `config.local.json` or environment variables, not published defaults.
- Keep the companion's core persona in `character-profile.md`; treat `config.local.json -> persona` as deprecated migration data.
- Keep presence cron payloads thin; the cron should call `companion_presence_tick.py`, not duplicate long writing instructions in runtime configuration.
- User-defined required events are life anchors, not guaranteed message sends.
- Day schedule events must keep `媒体信息`; leave it empty unless the matched event should produce photo, audio, video, or similar media.
- Final user-visible companion text must be first person from the companion's perspective.
- Do not expose internal JSON, code blocks, step names, debug output, local paths, account ids, channel ids, or session ids in owner-facing messages.
- Do not claim setup or upgrade is complete before a real validation command passes.

## Read This First For Real Setup Or Upgrade

Always read:
- [references/standard-init-upgrade-flow.md](./references/standard-init-upgrade-flow.md)
- [references/configuration.md](./references/configuration.md)
- [references/contract-schema.md](./references/contract-schema.md)

## Choose The Right Reference

- first-time setup or rebuild:
  - [references/first-time-setup.md](./references/first-time-setup.md)
  - [references/agent-first-time-qa-template.md](./references/agent-first-time-qa-template.md)
  - [references/required-events-and-cron.md](./references/required-events-and-cron.md)
- OpenClaw runtime wiring:
  - [references/presence-integration.md](./references/presence-integration.md)
- private-life layer:
  - [references/private-life-layer.md](./references/private-life-layer.md)
  - [references/private-life-cron-templates.md](./references/private-life-cron-templates.md)
  - [references/private-life-prompt-templates.md](./references/private-life-prompt-templates.md)
- custom required event anchors:
  - [references/required-events-and-cron.md](./references/required-events-and-cron.md)
- legacy upgrades:
  - [references/standard-init-upgrade-flow.md](./references/standard-init-upgrade-flow.md)
  - [references/script-contract-v2-migration.md](./references/script-contract-v2-migration.md)

## Version Notes

### 2.1.3

Version 2.1.3 moves the cron-side current-event decision into `scripts/companion_presence_tick.py`. The visible cron should run in an isolated session and only call that wrapper; the wrapper performs fresh prepare deterministically, then starts the stable companion session only for matched events. Presence writing must run a small public web search for the matched event, and media events now commit state after visible text delivery so media failure does not block later events.

### 2.1.2

Version 2.1.2 returned media delivery to the native OpenClaw completion flow by running `companion-presence` in a stable companion session. Text sends first, media generation runs asynchronously, and the completion turn in the same companion session sends media.

### 2.1.1

Version 2.1.1 changes `companion-presence` to a stateless single-turn runtime task. Continuity remains in local state files, and event media callbacks must use a self-contained payload instead of relying on a long-lived companion session history.

### 2.1.0

Version 2.1.0 is the public release cleanup for the simplified presence companion. It removes git-local packaging assumptions, keeps ClawHub ignore rules authoritative, preserves the generic internet-search day-schedule rule, and checks that local maintenance Markdown does not enter the publishable surface.

### 2.0.4

Version 2.0.4 hardens the generic day-schedule templates. It preserves the mandatory internet-search material rule without local profile examples, removes stale upgrade links, cleans finished schedule examples so they do not contain generation constraints, and clarifies first-time setup plus old-install migration.

### 2.0.3

Version 2.0.3 improves the published skill surface. It rewrites the main skill entry as a product-first quick-start page, removes an unreferenced optional source note from the package, and keeps the release smoke fixture aligned with the current runtime state schema.

### 2.0.2

Version 2.0.2 finishes the release-hardening pass for publishing. It keeps local runtime state out of the ClawHub package, documents the OpenClaw async media callback flow, and validates the publishable release surface before upload.

### 2.0.1

Version 2.0.1 hardened the 2.0 release surface, removed tests from the ClawHub package, tightened week/day generation quality, and added event-level media instructions through the OpenClaw async media callback flow.

### 2.0.0

Version 2.0.0 made the presence runner the only default active path by merging `scripts/companion_ping.py` into `scripts/companion_run.py` and removing the old render/full path from the default release surface.

## Maintainer Release Gate

Before publishing a new version, run:

```bash
python3 scripts/validate_release.py --root <SKILL_DIR> --config <CONFIG>
```

The validator compiles scripts, validates JSON and Markdown assets, runs the presence dry-run flow, checks the runner contract, and scans the release surface for private channel identifiers and obsolete cron contract terms.