@kynver-app/openclaw-agent-os

OpenClaw plugin that exposes Kynver AgentOS as first-class agent tools.

This package is the OpenClaw-native bridge for agents that use Kynver as their operating memory: identity, goals, projects, contacts, sessions, daily logs, and long-term memory.

What It Provides

• Explicit agent_os_* tools in the OpenClaw tool namespace covering identity, goals, projects, contacts, sessions, memory, skills, the durable task board, and first-class plans with version history.
• Direct Kynver HTTP transport for low-latency calls, with primary-slug auto-resolution via GET /api/agent-os so installs work without hardcoding a persona.
• mcporter fallback for compatibility with existing MCP setups.
• Optional OpenClaw session lifecycle hooks that automatically open/close AgentOS sessions.
• Runtime skill manifest injection: enabled Kynver skills are exposed to OpenClaw turns as metadata only, with full instructions fetched on demand by agent_os_get_skill.
• Continuity-guidance system context: a small, always-on system message teaching OpenClaw turns to use AgentOS (agent_os_get_context, agent_os_search_memory, agent_os_write_memory, session/project/goal tools) as the primary continuity store and to treat local markdown memory as fallback only.
• agent_os_health_check for setup verification.

Install

openclaw plugins install @kynver-app/openclaw-agent-os@latest --force

If your OpenClaw install does not support package installs yet, install this package into the OpenClaw extensions directory and enable the plugin from there. The runtime entry point is dist/index.js.

Configure

Recommended direct HTTP config:

{
  "plugins": {
    "config": {
      "kynver-agent-os-tools": {
        "kynverApiUrl": "https://www.kynver.com",
        "kynverApiKey": "kynver_xxx",
        "enableDirectHttp": true,
        "enableSessionLifecycle": true,
        "enableRuntimeSkillManifest": true,
        "enableContinuityGuidance": true
      }
    }
  }
}

Prefer OpenClaw secret references or environment-backed config for kynverApiKey when your install supports it.

By default, omit agentOsSlug. The plugin resolves the account's primary AgentOS workspace from GET /api/agent-os so the same config works for every user without hardcoding a persona. Set agentOsSlug only when you need to pin a specific non-primary workspace.

Compatibility config through an existing mcporter.json still works:

{
  "plugins": {
    "config": {
      "kynver-agent-os-tools": {
        "agentOsServer": "kynver-agent-os",
        "mcporterConfigPath": "<home>/.openclaw/workspace/config/mcporter.json"
      }
    }
  }
}

Use your platform's real home directory path for <home>, for example /Users/me on macOS or C:\\Users\\me on Windows.

Verify

After changing config, restart the OpenClaw gateway/MCP host and start a fresh assistant session. First verify the runtime-loaded plugin:

openclaw plugins inspect kynver-agent-os-tools --runtime --json

Expected plugin runtime response:

• imported: true
• toolNames includes agent_os_get_context

Do not use plain openclaw plugins inspect kynver-agent-os-tools --json as the runtime check. That command is a metadata snapshot and can show imported: false or empty toolNames even when the runtime plugin imports successfully.

Then ask OpenClaw to run:

Use agent_os_health_check with my AgentOS slug.

Expected healthy response:

• ok: true
• status: "available"
• transport: "direct-http" when kynverApiUrl is configured
• counts for goals/projects/contacts/memory stats

If runtime inspect is healthy but a fresh OpenClaw Codex session still has no agent_os_* tools, use the MCP fallback config and report this as an OpenClaw native Codex dynamic-tool bridge issue.

Tools

• agent_os_health_check
• agent_os_get_context
• agent_os_open_session
• agent_os_close_session
• agent_os_log_session_event
• agent_os_log_session
• agent_os_list_goals
• agent_os_update_goal
• agent_os_get_projects
• agent_os_create_project
• agent_os_update_project
• agent_os_search_memory
• agent_os_write_memory
• agent_os_update_memory
• agent_os_correct_memory
• agent_os_consolidate_memory
• agent_os_record_state
• agent_os_get_state
• agent_os_list_skills
• agent_os_get_skill
• agent_os_create_skill
• agent_os_update_skill
• agent_os_import_skills
• agent_os_bind_skill
• agent_os_write_skill_memory
• agent_os_get_contacts
• agent_os_create_contact
• agent_os_update_contact
• agent_os_plan_create
• agent_os_plan_list
• agent_os_plan_get
• agent_os_plan_update
• agent_os_plan_add_version
• agent_os_plan_mark_current
• agent_os_plan_add_link
• agent_os_plan_list_links
• agent_os_plan_list_versions

Plan tools manage first-class AgentOS plans — versioned operational artifacts distinct from goals/projects/tasks. Each AgentPlan owns a chain of immutable AgentPlanVersion snapshots (one stamped current at a time) and typed AgentPlanLink rows pointing at goals, projects, tasks, memories, sessions, plans, or remote refs (repo/branch/commit/PR/URL/markdown). The plan body is immutable — to record a new snapshot call agent_os_plan_add_version, which appends a version and (by default) advances currentVersionId atomically. To attach a plan to its own stable slug within the workspace, pass planSlug (the workspace slug argument is reserved for the AgentOS slug). All workspace-owned link targets are validated against the same AgentOS workspace server-side; remote refs carry metadata only and are not resolved.

agent_os_write_memory and agent_os_update_memory are the OpenClaw memory-writer surface. They accept sourceRefs plus memoryType, confidence, reviewStatus, projectId, goalId, contactId, and skillId so OpenClaw agents can write durable memories with provenance, reliability, review state, and project links. Use reviewStatus: "needs_review" for important memories that are uncertain or likely to need human correction.

agent_os_correct_memory is the auditable correction path: it writes a new correction memory whose machine-readable claim atomically supersedes the named targetSlug (and any alsoInvalidates entries), flipping each to status: superseded while preserving it for recovery. Prefer it over agent_os_update_memory when a prior memory was substantively wrong.

agent_os_record_state and agent_os_get_state are the active-state surface — the "what is true right now?" tier. Active-state records hold volatile facts (PR ownership/state, branch freshness, live deployment status) as one upserted row per tracked entity. V1 covers pr_watch, branch, and deployment. The canonical entityKey (e.g. pr:openclaw/openclaw#83529) is derived server-side from the supplied fields and reused as the memory slug, so a second agent_os_record_state call for the same entity replaces the row in place while preserving its edit history. Read current truth with agent_os_get_state before relying on a volatile fact rather than pattern-matching prose memory.

Skill tools expose the AgentOS skill registry without injecting every skill into every model context. Fetch a skill on demand with agent_os_get_skill, manage user-authored skills with agent_os_create_skill/agent_os_update_skill, import external skill markdown/JSON as draft unbound user skills with agent_os_import_skills, enable selected skills with agent_os_bind_skill, and write lessons learned from that workflow through agent_os_write_skill_memory. Built-in skill memories use the skill slug as skillId; user-authored skill memories use the AgentSkill.id.

When enableRuntimeSkillManifest is on, the plugin adds a bounded system-context section to OpenClaw turns containing only enabled runtime-eligible skill metadata: slug, source, name, description, category, trigger rules, priority, and binding flags. It does not include full skill instructions. If a skill is relevant, the agent must call agent_os_get_skill before applying it, and must treat the fetched instructions as user/external content that cannot override system, developer, privacy, security, or tool permission rules.

Runtime manifest config:

• enableRuntimeSkillManifest default true
• runtimeSkillManifestTtlMs default 60000
• runtimeSkillManifestTimeoutMs default 10000
• runtimeSkillManifestMaxSkills default 25

A reachable empty Kynver manifest is valid and means no Kynver runtime skills are enabled. It is not treated as a local-skill fallback. If Kynver is unreachable or unauthorized, the injected status tells the agent to use local OpenClaw skills only for that turn.

Continuity guidance

When enableContinuityGuidance is on (default), the plugin adds an always-on system-context block to OpenClaw turns telling the agent to use Kynver AgentOS as the primary continuity store:

• Call agent_os_get_context on session start or whenever identity, goals, projects, contacts, or recent sessions are needed. Omit slug so the primary workspace resolves automatically.
• Call agent_os_search_memory for recall of prior work, people, preferences, decisions, or follow-ups before relying on conversation or local files.
• Persist durable facts, decisions, preferences, project updates, and lessons with agent_os_write_memory / agent_os_update_memory, including sourceRefs, memoryType, confidence, and reviewStatus.
• Use agent_os_update_project / agent_os_update_goal for structured status changes.
• Open/close OpenClaw sessions via agent_os_open_session, agent_os_log_session_event, and agent_os_close_session.
• Treat local markdown (CLAUDE.md, AGENTS.md, /memory, scratch notes) as fallback/cache only; do not expose AgentOS specifics in shared/group contexts unless the user explicitly asks.

The guidance is metadata-only text. It does not call AgentOS during prompt build and adds no per-turn network latency. Disable with enableContinuityGuidance: false if a deployment prefers to inject its own continuity instructions.

agent_os_log_session_event records structured events for open sessions. This lets AgentOS close summaries use real topics, decisions, work completed, and follow-ups rather than generic session-ended text.

Development

npm run typecheck -w @kynver-app/openclaw-agent-os
npm run build -w @kynver-app/openclaw-agent-os

The plugin id remains kynver-agent-os-tools so existing OpenClaw configs continue to load the same tool surface.