Tools
Artist Runtime
By OpenClaw plugin that runs an autonomous musician: persona-driven song ideas, lyrics, Suno prompt packs, append-only ledgers, and gated publishing.
Install
npm install
npmREADME
# OpenClaw Artist Runtime
OpenClaw Artist Runtime turns an OpenClaw agent into a **public autonomous AI musician**.
It runs on a Mac as an OpenClaw plugin, creates songs from its own artistic state,
generates music with Suno, and shares finished or in-progress work to selected
public platforms such as X, Instagram, and TikTok.
This repository is structured as a **distribution-ready OpenClaw native plugin package**.
It is intended to be published to ClawHub and/or npm after implementation and review.
## Requirements
- **macOS** — the Suno browser lane and operator helper scripts are built and
tested on macOS.
- **Node.js >= 20.**
- **A host OpenClaw install** with the `openclaw` CLI on `PATH`. This package is
an OpenClaw plugin loaded by the gateway, not a standalone app.
- **For the live Suno browser lane:** a Playwright Chromium binary
(`npx playwright install chromium`) plus a logged-in Suno browser profile.
- **For X distribution:** the `bird` CLI on `PATH` with an authenticated local
session.
- Instagram and TikTok are optional, frozen lanes and need no setup by default.
## Product stance
Artist Runtime is not a private writing assistant. It is a public artist daemon.
The producer chooses:
- which platforms the artist uses;
- how far Suno generation may run autonomously;
- which social post types can be published automatically;
- budgets, cadence, and hard stops;
- how much reporting the producer receives.
## Install shape
After publication, the target install command is:
```bash
openclaw plugins install clawhub:@yzhonda/openclaw-artist-runtime
```
or, if using npm fallback:
```bash
openclaw plugins install npm:@yzhonda/openclaw-artist-runtime
```
## For operators
If you installed this plugin through OpenClaw or npm, the published tarball
contains everything needed to run and operate the artist daemon. Start here:
- `docs/OPERATOR_QUICKSTART.md` — gateway start, probes, arm flags, dry-run
verification, and the explicit live-publish handoff boundary.
- `docs/PRODUCER_CONSOLE.md` — Producer Console reference for the bundled UI
and the fallback inline shell.
- `docs/PERSONA_CANONICAL.md` — persona five-file ownership and generated
projection contract.
- `docs/RUNTIME_SETTINGS.md` — runtime settings layers, precedence, and
env-only diagnostics.
- `docs/PRIVATE_DATA_ROOT.md` — optional `OPENCLAW_ARTIST_PRIVATE_ROOT` for a
separate private data checkout (not required for CI).
- `docs/OPERATOR_RUNBOOK.md` — manual doctor, log rotation, and runtime state
snapshot helpers.
- `docs/TROUBLESHOOTING.md` — symptom-first recovery decision tree linked to
reason-code anchors.
- `docs/ERRORS.md` — compact reason-code catalog for Console badges, logs, and
incident notes.
- `docs/CONNECTOR_AUTH.md` and `docs/GATEWAY_AUTH.md` — credential probes for
X (Bird), Instagram, TikTok, and the gateway auth surface.
- `docs/API_ROUTES.md` — live plugin HTTP route catalog.
For a security-sensitive report, follow `SECURITY.md`. For data retention and
local-state policy, see `PRIVACY.md`.
## Current status
This package now includes a working dry-run runtime with a bundled Producer Console,
repo-local OpenClaw sandbox tooling, persisted-config-aware routes, live-safe route
dispatch under the current OpenClaw Gateway matcher, and CI regression gates on
`main` pushes and pull requests.
- Full-cycle smoke tests cover `planning → prompt_pack → suno_generation →
take_selection → asset_generation → publishing (dry-run) → completed`, and a
second rotation into `song-002`, with zero external calls (`spawn` and `fetch`
are mocked and asserted unused).
- Producer Console exposes a live config editor for `autopilot` and
`distribution.platforms.*`, ticker status, recent X dry-run results, and a
dry-run simulate-reply form backed by plugin API routes only.
- Producer Console config editing now covers both platform enablement and
`distribution.platforms.*.authority`, so X / Instagram / TikTok safety modes
can be switched live from the bundled UI or the fallback inline shell.
- Connector readiness is now documented end to end: X uses the `bird` CLI and
its local auth store, while Instagram and TikTok expose env-based auth probe
contracts through `CAPABILITIES.md` and `SECURITY.md` so operators know which
credentials must exist before any live authority is enabled.
- Producer Console now surfaces Suno worker lifecycle and automation outcomes end
to end: `currentRunId`, `lastImportedRunId`, `lastCreateOutcome`, and
`lastImportOutcome` are exposed from `/api/suno/status` and rendered in both
the bundled React UI and the fallback inline Console.
- The Suno outcome surface is now isolated into a dedicated compact component
with explicit dry-run badges on the latest create/import outcomes, so the
operator can distinguish simulated automation from future live worker results
at a glance.
- All read routes, mutating routes, and `/api/config/update` now resolve config
through the same persisted runtime-config pattern, so Console behavior is
consistent when `runtime/config-overrides.json` is present.
- Route dispatch is now hardened against the current OpenClaw Gateway's literal
`:param` matcher behavior: platform test routes are registered statically and
the `songs`, `alerts`, `platforms`, and `suno` API families use prefix
dispatch so the existing URLs still work live.
- Suno worker automation now has a full mock-only skeleton: lifecycle state,
manual login handoff, create/import driver contracts, connector wiring, and
persisted outcomes are all in place without executing a real browser or Suno run.
- Social connector skeletons are now aligned across all three platforms:
X/Bird, Instagram, and TikTok each expose auth probing plus fail-closed
publish/reply behavior, with Instagram/TikTok staying mock-only and dry-run-safe.
- Repo-local verification includes `scripts/openclaw-local-gateway`,
`scripts/openclaw-local-http-smoke.sh`, `scripts/openclaw-local-write-smoke.sh`,
and `scripts/openclaw-local-ticker-observe.sh`.
- The repo now includes a GitHub Actions CI workflow that runs `typecheck`, `test`,
and `build` on pushes and pull requests to `main`.
- CI regression gates have stayed stable through repeated post-fix runs, including
the workspace-template tracking correction and the lock-file-free workflow update.
- `workspace-template/artist/*` and `workspace-template/songs/.gitkeep` are tracked,
so fresh CI/workspace bootstrap runs get the same artist files as local development.
- Real Bird / Instagram / TikTok posting, real Suno browser automation, and real
platform writes are **not** enabled by default and require explicit operator action.
- `autopilot.dryRun` defaults to `true`; the plugin ships safe-by-default.
- Producer Console uses a bundled React app from `ui/dist/` when available and falls
back to an inline inspection shell when the bundle is missing or stale.
See `CHANGELOG.md` for the active feature set.
## Persona setup ownership
Producer Console setup is not a raw Markdown editor. The canonical contract lives
in `src/services/personaCanonical.ts` and exposes only these user-input surfaces:
| Surface | Backing file | User edits |
| --- | --- | --- |
| Artist Core | `ARTIST.md` | artist concept, sound, obsessions, lyrics stance, public/social voice |
| Conversation Voice | `SOUL.md` | conversational tone and refusal style |
| Producer Context | `PRODUCER.md` | producer facts and preferences that change creative decisions |
`artist.identity.displayName` and `artist.identity.producerCallname` are runtime
config fields. `IDENTITY.md` is a derived read-only projection, and `INNER.md` is
runtime-managed internal state. Setup must not ask the producer to edit either
file directly. `artist/CURRENT_STATE.md` is also runtime-managed and should not
be used for producer notes. The default runtime workspace is
`.local/openclaw/workspace`; repo-root persona files are package/reference files,
not the live artist workspace unless an operator explicitly sets
`artist.workspaceRoot` to the repository root.
See `docs/PERSONA_CANONICAL.md` for the full five-file ownership map.
## Key package files
- `openclaw.plugin.json` — manifest, config schema, UI hints, capability declaration.
- `package.json` — npm/ClawHub package metadata and OpenClaw compatibility block.
- `SECURITY.md` — credential, browser profile, external action, and reporting policy.
- `PRIVACY.md` — local data, ledgers, external transmissions, deletion model.
- `CAPABILITIES.md` — exact advertised tools, hooks, services, routes, side effects.
- `PUBLISHING.md` — ClawHub/npm pre-publish checklist.
- `MARKETPLACE.md` — listing copy, disclosure text, and packaging strategy.
## Runtime architecture
```text
OpenClaw Gateway
└─ Artist Runtime plugin
├─ Producer Console HTTP route
├─ Autopilot service
├─ Suno Browser Worker
├─ Social Distribution Worker
├─ Tools / Hooks / Authority Guards
├─ Prompt Ledger / Audit Log
└─ Connectors: Bird, Instagram, TikTok
```
## Safety defaults
The package schema includes autonomous defaults because the product is a public
artist daemon, but `autopilot.dryRun` defaults to true. Production release must make
initial setup explicit before external side effects occur.
Hard stops are mandatory:
- login challenge;
- CAPTCHA;
- payment prompt;
- UI mismatch;
- policy uncertainty;
- platform capability failure.
## Suno
Suno integration is designed around a background logged-in browser profile or a manual
copy fallback. It must not use CAPTCHA bypass, credential capture, or non-consensual
voice/artist imitation flows.
The bundled Suno knowledge pack includes `sunomanual` material by usedhonda
(Copyright 2025-2026) under MIT. The Artist Runtime code remains under
its own repository license, while the copied knowledge files and embedded
lyrics/style prompt instructions retain their `sunomanual` attribution and
MIT attributi
... (truncated)
tools
Comments
Sign in to leave a comment