Skip to content

README.md

Latest commit

 

History

History
285 lines (225 loc) · 12.3 KB

README.md

File metadata and controls

285 lines (225 loc) · 12.3 KB
Raw

ORION Core Gateway (OpenClaw Workspace)

This repo is an OpenClaw workspace for ORION core: a local-first admin copilot and safe orchestration system.

Design goals:

  • single user-facing ingress (ORION)
  • a small default specialist surface for core work
  • identities are generated to reduce drift
  • delegation is structured and auditable (Task Packets)
  • secrets never enter Git
  • admin-copilot usefulness over novelty surfaces or product sprawl

Start Here

If you are new to the repo, start with docs/ORION_START_HERE.md.

Runtime Model

  • ORION (agentId: main) is the only user-facing bot (Telegram/Discord/Slack when configured).
  • Default ORION core delegation lanes are ATLAS, POLARIS, WIRE, and SCRIBE.
  • Optional retained lanes are LEDGER and EMBER.
  • NODE, PULSE, and STRATUS remain internal implementation detail behind ATLAS.
  • PIXEL and QUEST remain available only as non-core extension lanes and are not part of the default ORION core routing surface.
  • ORION delegates using sessions_spawn plus a Task Packet, and uses sessions_yield for active long-running sessions while keeping Task Packets as the durable record (see docs/TASK_PACKET.md and docs/NATIVE_SUBAGENT_CONTROL_PLANE.md).
  • Specialists return results to ORION only (never message Cory directly).
  • ORION local installs should pin tools.profile to coding; as of OpenClaw 2026.3.x, new local installs default to messaging when unset.
  • Checked-in runtime templates now default ORION to openrouter/openrouter/free with cheap/free fallbacks first; premium OpenAI/Codex lanes are explicit opt-in only.

Go Live (macOS)

Required for reliable heartbeats/cron:

openclaw config validate --json
openclaw gateway install
openclaw gateway start
openclaw doctor --repair
openclaw security audit --deep
openclaw channels status --probe

Verify agents are configured:

openclaw agents list --bindings
openclaw models status

Latest local/runtime baseline:

  • Runtime verified on 2026-04-29 against OpenClaw 2026.4.27.
  • Historical upgrade note remains in docs/OPENCLAW_2026_3_13_UPGRADE_NOTES.md.
  • Current sweep baseline and follow-on decisions live in:
    • docs/ORION_RUNTIME_BASELINE_2026_04_07.md
    • docs/ORION_TOOL_PILOTS_2026_04.md
    • docs/ORION_AGENT_SYSTEM_SWEEP_2026_04_07.md

Current verification snapshot (2026-04-29):

  • openclaw --version returned OpenClaw 2026.4.27.
  • openclaw config validate --json returned {"valid":true,...}.
  • openclaw gateway status --json returned a healthy loopback LaunchAgent and openclaw gateway call status --json reported the current 2026.4.x runtime.
  • Live runtime plugin entries include acpx, bluebubbles, discord, memory-core, minimax, open-prose, openai, openrouter, slack, and telegram.
  • Live runtime memory slot is memory-core, and dreaming is enabled in runtime.
  • ACPX is enabled in the live runtime for bounded specialist execution.
  • ACPX live usage is pinned to ATLAS-owned bounded work with permissionMode=approve-reads, nonInteractivePermissions=fail, and pluginToolsMcpBridge=false.
  • Firecrawl remains disabled in the live runtime because FIRECRAWL_API_KEY is not configured.
  • Checked-in templates still keep memory-lancedb as the conservative default while the live runtime uses memory-core with dreaming enabled.
  • OpenClaw 2026.4.20 and 2026.4.21 added stricter owner-command auth, startup/health-reporting improvements, session pruning by default, cron runtime-state splitting (jobs-state.json beside jobs.json), and better doctor/plugin dependency repair paths.
  • OpenClaw 2026.4.27 adds ORION-relevant Telegram startup/send/topic-cron fixes, plugin registry/startup hygiene, strict model fallback behavior, and models.pricing.enabled for low-cost/offline startup.
  • Deferred 2026.4.27 surfaces: DeepInfra, Yuanbao, QQBot, Matrix, Slack, Docker GPU passthrough, and mobile node presence.
  • The older OPENCLAW_GATEWAY_TOKEN LaunchAgent audit warning from 2026.4.14 is not the current verified state on this machine; the current LaunchAgent config audit is clean, but still verify after reinstalls.
  • The bundled Discord runtime dependency stack required a local npm rebuild after the 2026.4.21 upgrade; gateway and Telegram recovered cleanly afterward.
  • openclaw skills list confirms ClawHub-backed skill discovery is available in the local runtime.
  • browser and firecrawl remain bundled plugin surfaces that are not allowlisted in the current live config.
  • make incident-bundle writes a read-only ORION ops bundle under tmp/incidents/ plus a stable summary at tasks/NOTES/orion-ops-status.md.

Capability intake brief:

  • docs/ORION_RUNTIME_BASELINE_2026_04_07.md
  • docs/ORION_TOOL_PILOTS_2026_04.md
  • docs/ORION_AGENT_SYSTEM_SWEEP_2026_04_07.md
  • Historical context:
    • docs/OPENCLAW_CAPABILITY_INTAKE_2026_03_18.md
    • docs/ORION_TOOLSET_ADOPTION_2026_03_22.md
  • docs/ORION_FUNCTIONAL_REVIEW_2026_04_06.md
  • docs/OPENCLAW_MEMORY_DREAMING.md

Recovery

Runbook:

  • docs/RECOVERY.md

Assistant Focus

Primary assistant posture:

  • ORION is a bounded-proactive admin copilot.
  • POLARIS is the default internal route for reminders, calendar prep, notes capture, follow-through, and daily review.
  • Telegram remains the primary user-facing surface.
  • Primeta is available as an optional avatar/presentation layer via MCP; it does not replace ORION's routing, Task Packets, or Telegram/TTS defaults.

Deterministic assistant commands:

  • /today -> agenda from calendar + reminders + delegated work + open tickets
  • /capture <text> -> quick admin capture queued to POLARIS
  • /followups -> waiting-on items and POLARIS queue
  • /review -> concise daily review / next actions

Generated assistant artifacts:

  • memory/ASSISTANT_PROFILE.md
  • tasks/NOTES/assistant-agenda.md
  • tasks/NOTES/error-review.md
  • tasks/NOTES/session-maintenance.md

Internal reliability review:

  • python3 scripts/orion_error_db.py review --window-hours 24 --json
  • AUTO_OK=1 python3 scripts/session_maintenance.py --repo-root . --agent main --fix-missing --apply --doctor --min-missing 50 --min-reclaim 25 --json
  • python3 scripts/orion_incident_bundle.py --repo-root . --write-latest --json
  • docs/ORION_ERROR_REVIEW.md

Memory/dreaming:

  • ORION keeps memory-lancedb as the active checked-in template default for now.
  • Live runtime has moved to memory-core with dreaming enabled; treat that as runtime state, not a blanket repo default.
  • OpenClaw 2026.4.14 is the current verified runtime; dreaming remains documented here as the active memory-core path.
  • See docs/OPENCLAW_MEMORY_DREAMING.md before switching the memory slot or enabling /dreaming.
  • For dreaming to populate short-term recall, ORION memory search must include memory in agents.list[].memorySearch.sources; sessions alone will not write the dreaming recall store.
  • For deterministic direct ORION turns, prefer the guarded wrapper path over raw openclaw agent:
    • make dreaming-status
    • make dreaming-help
    • make dreaming-on
    • make dreaming-off
  • Non-destructive preview:
    • make dreaming-preview
    • writes tmp/openclaw_memory_dreaming_preview_latest.json
    • writes tmp/openclaw_memory_dreaming_preview_latest.md
    • reports whether a local short-term recall store exists yet

Standard operator health bundle:

  • Run make operator-health-bundle after gateway, model, or memory changes.
  • By default it stays read-only: gateway status, models status, memory status, and memory rem-harness.
  • Live token spend is opt-in via ALLOW_LIVE_MODEL_PROBE=1 and/or ALLOW_LIVE_SMOKE=1.
  • Repo planning and code-mod work should stay in low-cost mode by default; see docs/LOW_COST_MODE.md.
  • Artifacts:
    • tmp/openclaw_operator_health_bundle_latest.json
    • tmp/openclaw_operator_health_bundle_latest.md

Core Boundary

ORION core owns:

  • admin-copilot Telegram commands (/today, /capture, /followups, /review)
  • the private ORION Telegram Main Mini App (/orion)
  • task packets, delegated-job state, and core maintenance loops
  • routing, retrieval, drafting, safety, and proof-driven execution

ORION core does not own by default:

  • trading, market, game, or media product surfaces
  • product-specific Telegram commands
  • product-specific scheduled jobs

Non-core surfaces now live behind explicit extension seams. See:

  • docs/ORION_SINGLE_BOT_ORCHESTRATION.md
  • docs/ORION_EXTENSION_SURFACES.md
  • apps/extensions/

Telegram Surfaces

Primary Telegram commands in ORION DM:

  • /today for agenda from calendar + reminders + delegated work + open tickets
  • /capture <text> for quick capture queued to POLARIS
  • /followups for waiting-on items and POLARIS queue
  • /review for concise daily review / next actions
  • /orion for the private Telegram Main Mini App
  • /agents for the core agent dashboard
  • /dreaming ... for guarded memory/dreaming controls

Mini App docs:

  • docs/ORION_TELEGRAM_MINI_APP.md

Optional Avatar Layer

Primeta can sit on top of ORION as an opt-in avatar layer for spoken summaries and animated reactions.

  • Keep it presentation-only.
  • Do not treat it as a new user-facing ingress.
  • Do not make normal ORION delivery depend on Primeta availability or OAuth state.

Operator docs:

  • docs/PRIMETA_AVATAR_LAYER.md
  • scripts/primeta_avatar.py

Discord (Optional)

OpenClaw includes a bundled Discord channel plugin (disabled by default). ORION core keeps Discord available as an optional request/update surface, but not as a reason to widen the default specialist or product surface.

Setup:

  • docs/DISCORD_SETUP.md

PDF Review Flow

OpenClaw 2026.3.x introduced first-class PDF analysis plus sessions_spawn inline attachments for subagents.

For ORION's preferred workflow, see:

  • docs/PDF_REVIEW_WORKFLOW.md

Workspace Contract (OpenClaw)

OpenClaw injects these workspace files on the first turn of new sessions:

  • AGENTS.md
  • SOUL.md
  • TOOLS.md
  • IDENTITY.md
  • USER.md
  • BOOTSTRAP.md (one-time; delete after go-live)

Repository Layout

  • src/core/shared/
    • Shared identity layers included in every generated SOUL.
  • src/agents/
    • Role definitions (source of truth).
  • scripts/soul_factory.sh
    • Generates agents/<AGENT>/SOUL.md.
  • agents/
    • Generated SOUL artifacts.
  • docs/TASK_PACKET.md
    • Delegation spec (cron payloads + ORION -> specialist).
  • tasks/QUEUE.md
    • Human-readable queue for ORION triage.
  • tasks/INBOX/*.md
    • Per-agent inboxes for specialist assignments.
  • docs/ORION_EXTENSION_SURFACES.md
    • Boundary and handoff model for non-core product surfaces.
  • docs/REPO_HYGIENE.md
    • What stays versioned versus what should remain local runtime state.
  • apps/extensions/
    • Moved extension-owned Telegram/product surfaces that are not part of the default ORION core runtime path.
  • memory/WORKING.md
    • Current working state (keep it lean).
  • skills/
    • Workspace skills (manual installs/updates).

Skill Ownership

  • The current per-agent skill and tool ownership matrix lives in docs/ASSISTANT_SKILLS.md.
  • Repo-wide cost policy and low-spend defaults live in docs/LOW_COST_MODE.md.
  • Use ClawHub as the standard discovery/update channel for skill review, but keep repo curation and policy review in the loop.
  • Treat setup-gated skills as pending setup, not live capability.

Regenerating SOULs

make soul

Do not hand-edit agents/*/SOUL.md. Change sources in src/core/shared/ or src/agents/ and re-run the Soul Factory.

Secrets

Do not commit secrets. See KEEP.md.

OpenClaw runtime config and credentials live under ~/.openclaw/ and must remain local.

CI / Reliability Gate

Local must-pass gate:

make ci

What it checks:

  • Python unit tests + Task Packet validation (npm test)
  • ShellCheck over bash scripts (scripts/ci_shellcheck.sh)
  • Promptfoo config validation and optional redteam gate:
    • docs/PROMPTFOO_GATE.md

Supported validation path:

  • Preferred: npm test
  • TypeScript-only: npm --prefix app run typecheck
  • Bare pytest -q is not the repo default and may use the wrong Python interpreter on macOS.

Opt-in live routing lane:

make routing-regression-live-dry-run
make routing-regression-live

Use this when you want the full local openclaw agent routing simulation plus baseline comparison without adding model-dependent runtime to the default CI gate.