Cyber Girlfriend

Owner-only proactive companion system

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 explicit invocation is:

Use $cyber-girlfriend to help me set up a 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 automation that runs the deterministic tick wrapper as an exact Gateway command payload
• 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 --no-record-pending

On OpenClaw versions that support command automations, cron invokes the wrapper directly with an exact argv payload; no model turn is used merely to launch the script. 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 derive a fresh dispatch-scoped companion session from the prepared run id. That session writes the first-person story, but text delivery goes through companion_presence_tick.py --send-story --story-stdin, which reloads the saved delivery contract from the dispatch lock, sends with the external OpenClaw CLI, and commits state only after successful text delivery. If the matched event asks for media, media generation starts after --send-story succeeds and finishes asynchronously. The wrapper also starts a deterministic recent-media watcher for the same dispatch session, so generated media is delivered through the prepared delivery contract even if the native completion turn falls back to Codex internal UI. Cross-event continuity comes only from the local state files, so archived runtime sessions are never reused.

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

• Do not run this skill through implicit discovery; the user must explicitly invoke $cyber-girlfriend.
• 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.
• Prefer an exact argv command payload for companion-presence; do not spend an isolated model turn only to run the wrapper. Use the legacy thin agent-turn payload only when the installed OpenClaw does not support command automations.
• Run companion-build-day-schedule with lightweight bootstrap context because its payload explicitly names every required project input.
• 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.
• Before writing local config or state, running public-web search, creating/updating/enabling recurring jobs, or sending the first controlled verification message, preview the exact scope and wait for explicit user confirmation.
• Pause is reversible: disable the exact builder and presence jobs without deleting local config or state. Permanently remove jobs only after a separate explicit request.
• 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/configuration.md
• references/contract-schema.md

Choose The Right Reference

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

Version Notes

2.2.0

Version 2.2.0 adapts the scheduled runtime to OpenClaw command automations and archived-session enforcement. companion-presence now runs companion_presence_tick.py as an exact argv Gateway command instead of starting a full isolated model turn whose only job was to execute the wrapper and reply NO_REPLY. Each matched event uses a fresh dispatch-scoped companion session so OpenClaw never has to resume an archived long-lived runtime session. If the external CLI cannot resolve the configured WeChat plugin channel, the fixed send entrypoint uses its existing explicit-contract direct fallback and keeps a failed delivery retryable. The model-backed companion-build-day-schedule job keeps its generation workflow but enables lightweight bootstrap context because its payload already lists the required inputs.

中文说明：2.2.0 把 companion-presence 改成 OpenClaw 原生 command automation，用精确 argv 直接运行 wrapper，不再每 15 分钟先启动一次 Codex turn。命中事件后为本轮派生新的 dispatch session，不再复用可能已归档的长期 session；如果外部 CLI 也找不到自定义微信渠道，固定发送入口会按同一 delivery contract 使用既有直连兜底，并把失败发送保留为可重试。这样可以同时避开 turn-accepted 卡住、归档会话拒绝启动和空转模型上下文；每日 日程 builder 仍使用模型，但启用轻量上下文，只加载任务明确要求的项目输入。

2.1.9

Version 2.1.9 makes text delivery use the same deterministic wrapper boundary as media delivery. The stable companion session must not call the runtime message(action="send") tool for presence text. It writes the story and calls companion_presence_tick.py --send-story --story-stdin; that helper loads the saved contract from presence-dispatch.json, sends through openclaw message send --channel/--target/--account --message, and then runs state_commit.command. Media events start async media generation only after --send-story succeeds.

中文说明：2.1.9 把正文投递也收回到固定脚本入口，不再依赖 Codex runtime 的 message 工具解析自定义渠道。稳定 session 只负责写正文和调用 --send-story --story-stdin；脚本按 dispatch lock 里的 delivery_contract 显式发文本，成功后再提交状态。这样新用户和老用户都统一走外部 OpenClaw CLI 的真实渠道表，避免 Unknown channel 或 current chat 误路由。

2.1.8

Version 2.1.8 makes media delivery independent of model follow-up behavior. For media events, companion_presence_tick.py now starts a background recent-media watcher immediately after the stable companion session is launched; the watcher finds the next media task created by that stable session, waits for completion, extracts the generated media path, and sends it with the explicit delivery_contract. --watch-media-task remains the task-id-specific helper, and --send-media remains the direct send fallback.

中文说明：2.1.8 不再要求模型在媒体工具返回后“自觉”运行 watcher。wrapper 会自己启动后台 watcher，按稳定 session 和启动时间找到本次生成任务，然后用 delivery_contract 显式投递到真实渠道，避开 Codex runtime 的 internal-ui/current chat 误路由。

2.1.7

Version 2.1.7 adds deterministic media delivery entrypoints for async OpenClaw media tasks. After the main presence turn starts media generation, it runs companion_presence_tick.py --watch-media-task with the returned task id; the helper waits for the generated media path and sends through the explicit delivery_contract using openclaw message send --channel/--target/--account/--media. --send-media remains the direct completion fallback and retries once if a result indicates internal-ui or current-webchat routing.

中文说明：2.1.7 为异步媒体任务增加固定监控和投递入口。主 turn 启动媒体生成后立刻运行 --watch-media-task 等待任务完成并按 delivery_contract 显式发送到真实渠道；不再依赖 completion turn 自己理解 current chat。

2.1.6

Version 2.1.6 hardens OpenClaw CLI child processes launched by the presence wrapper so cron-inherited CA settings cannot reintroduce Keychain startup failures. It also keeps dispatch-lock startup acknowledgement and launch-error diagnostics in the release contract.

中文说明：2.1.6 加固了 presence wrapper 启动 OpenClaw CLI 子进程时的 CA 环境，避免 cron 继承的系统 CA 设置再次触发 Keychain 启动失败；同时保留稳定 session 启动确认和启动失败诊断能力。

2.1.5

Version 2.1.5 removes prompt wording that explicitly names concrete runtime tools while preserving the mandatory real web-search requirements for day-schedule generation and matched-event presence writing.

2.1.4

Version 2.1.4 removes the legacy visible mode field from the presence prepare contract and default wrapper command. There is now only one public presence flow: cron calls the deterministic wrapper, the wrapper prepares the current event, and matched events are handed to the stable companion session.

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.