@pingagent/openclaw-install

One-command install for the PingAgent OpenClaw adapter path into the external escalation and callback layer.

This is the path that turns an OpenClaw host into a durable collaboration node:

• the host gets a stable DID
• inbound work lands in stable collaboration sessions
• replies stay on the same collaboration thread
• summaries and handoff keep work alive across time
• the owner gets Host Panel or TUI as a real operator surface
• human delivery learns candidate reply targets from real traffic, promotes verified explicit targets, and sends only through explicit outbound instead of raw transport dumps or cross-session guesswork

This is not just an inbox bridge. It is the current strongest execution path that lets an OpenClaw agent stay reachable, request intervention, and keep callback / approval / repair work on the same control layer across time without making PingAgent pretend to own the runtime loop itself.

The default product model is now:

• Collaboration session
  • source of truth for raw external messages, task history, handoff, audit, degraded state, and repair
• External callback delivery
  • Human Delivery Binding and Notification Intent today
  • generalized as external target binding plus action / callback intent
  • ACK / Unresolved / Failed / Repair
• Action control
  • Action Inbox for approvals, callbacks, escalations, blocked work, and degraded follow-up
  • Decision Inbox as the approval-only subset
• OpenClaw adapter execution
  • External Escalation, Callback Resume, and Capability Token for high-risk actions
  • callback results always resume into the original stable collaboration session through hooks
  • high-risk external callback resume requires a valid token or a trusted local operator action

current-thread visibility remains available only as a deeper compatibility route. It is not part of the default OpenClaw onboarding story.

Transport choice:

• default landing
  • bridge
  • still the production-proven default today
• hidden beta
  • native channel beta
  • remains available for explicit evaluation, but it is not part of the default OpenClaw product path

Primary path:

• OpenClaw Session Runtime
  • IM ingress daemon
  • OpenClaw official webhooks (/hooks/pingagent)
  • @pingagent/mcp as the control surface

Opt-in beta path:

• OpenClaw native channel transport
  • local extension bundle: @pingagent/openclaw-channel
  • direct + text + eventId dedupe
  • bridge remains the default and fallback path
  • channel only replaces transport; it does not replace Action Inbox, Decision Inbox, or Projection Policy

Secondary path:

• Generic Skill Executor
  • PingAgentSkill + TaskExecutor
  • for non-OpenClaw long-running receivers

If You Only Read One Section

For most OpenClaw operators, the default path is now:

1. npx @pingagent/openclaw-install
2. read the final machine state:
   • activation_state=ready_waiting_inbound
   • or activation_state=blocked
3. if blocked, use the repair surface:
   • GUI: npx @pingagent/sdk web
   • headless: npx @pingagent/sdk host tui
4. if ready, let the runtime wait for inbound work or pending decisions
5. when a session appears, continue with:
   • pingagent_recent_sessions
   • pingagent_focus_session
   • pingagent_reply
6. when the thread objective or constraints change:
   • pingagent_session_summary
   • pingagent_handoff
7. use Action Inbox for callbacks, escalations, blocked work, degraded follow-up, and approvals
8. use Decision Inbox when you want only the approval slice

When the runtime looks unhealthy:

• check ready_waiting_inbound / degraded / blocked in Host Panel or TUI
• use the printed repair_action
• run npx @pingagent/openclaw-install fix-hooks only as a repair step, not as part of the normal first-run path

When a thread turns into maintained context or delegated work:

• use pingagent_session_summary
• use pingagent_handoff
• use the global Action Inbox when human intervention, callback, escalation, or approval is required
• use Decision Inbox when you want only the pending-approval slice
• keep Projection Policy on Balanced unless you intentionally want quieter or stricter notification behavior

Do not start with:

• pingagent_inbox as your normal receive loop
• pingagent_chat as the main OpenClaw operator loop
• host bootstrap as the primary install command
• manual hook editing when repair commands can fix the runtime

If you explicitly want to evaluate the native channel beta instead of the default bridge transport:

npx @pingagent/openclaw-install init-runner --channel
npx @pingagent/openclaw-install init-runner --channel --write
export PINGAGENT_OPENCLAW_TRANSPORT=channel

Use that only as an opt-in transport swap. Keep the existing bridge path available until the channel beta is validated in your environment.

Compatibility runners still default human delivery to:

export PINGAGENT_HUMAN_DELIVERY_MODE=bound_channel_reply

Recommended production mode, once you have confirmed at least one DM target and one group fallback target, is:

export PINGAGENT_HUMAN_DELIVERY_MODE=verified_explicit_notify

The intended migration path is:

1. let ingress learn Human Delivery Bindings from real human replies
2. import or promote those filtered candidates into Verified Delivery Targets
3. keep owner DM as priority 1 and workspace_default group as the fallback
4. switch the daemon to verified_explicit_notify

Why the main success standard is not current-thread visibility

The recommended model is:

• collaboration session
  • source of truth for raw external messages, task history, handoff, audit, degraded state, and repair
• human delivery
  • summaries, key conclusions, risks, pending decisions, and approval results sent through explicit reply targets when available

That is why current-thread visibility is not the main ingress success standard anymore. It remains available as a compatibility route, but correctness is defined by:

1. external work landing in a stable collaboration session
2. OpenClaw continuing work there
3. notification intents resolving to a real human binding and being delivered through explicit outbound

Install

npx @pingagent/openclaw-install

What it does:

1. writes / merges ~/.openclaw/openclaw.json with skills.entries.pingagent
2. copies the bundled PingAgent skill to ~/.openclaw/skills/pingagent
3. registers @pingagent/mcp through mcporter
4. initializes a stable PingAgent identity
5. creates a default trust policy file if missing
6. repairs the standard OpenClaw hooks block
7. verifies readiness
8. starts the local PingAgent ingress runtime

How to read the result:

• activation_state=ready_waiting_inbound
  • install succeeded, runtime is running, and the agent should wait for inbound work or pending decisions
• activation_state=blocked
  • install wrote the runtime, but at least one required dependency or hook path still needs repair

Default paths:

• identity: ~/.pingagent/profiles/openclaw/identity.json
• store: ~/.pingagent/profiles/openclaw/store.db
• trust policy: ~/.pingagent/profiles/openclaw/trust-policy.json

Recommended OpenClaw Flow

npx @pingagent/openclaw-install

Then:

• if the final state is ready_waiting_inbound, let the runtime wait for work
• if the final state is blocked, open the repair surface and follow the printed repair_action

Compatibility / advanced path:

npx @pingagent/sdk host bootstrap
npx @pingagent/openclaw-install init-runner --ingress --panel --write
npx @pingagent/openclaw-install verify-runtime --fix-hooks

This gives you:

• stable DID for the OpenClaw host
• ingress bridge from PingAgent into OpenClaw sessions
• a durable thread model instead of one-off receive/reply cycles
• a standard Host Panel launch path through npx @pingagent/sdk web or a panel runner service
• session-first MCP tools for reply / approvals / task status / trust policy
• agent-first workflow tools for capability card / session summary / first-class handoff
• human delivery with:
  • Action Inbox for approvals, callbacks, escalations, blocked work, and degraded follow-up
  • Decision Inbox as the approval-only subset
  • OpenClaw adapter execution state for runtime_runs, external_escalations, callback_resumes, and high-risk capability_tokens
  • Projection Policy: quiet / balanced / strict
  • Human Delivery Bindings as candidates, Verified Delivery Targets as the stable source of truth, Notification Intents, Delivery Attempts, and ACK / Unresolved / Failed / Repair
  • per-channel Capability Registry + Canary
  • explicit send / reply binding code paths for feishu, discord, telegram, slack, and whatsapp
• local Host Panel via http://127.0.0.1:3846/host-panel once npx @pingagent/sdk web or the panel daemon is running
• Host Panel selected-session actions for Reply, Approve Contact, Mark read, Copy Session Link, OpenClaw escalation Retry / Cancel / Approve / Reject, and advanced compatibility repair when intentionally needed
• a Basic / Advanced runtime view so operators can hide low-level session/debug fields until needed
• Ready / Degraded / Fix now status across Host Panel and headless TUI
• automatic polling_degraded fallback if webhook ingress becomes unhealthy

This is the standard path. install is now the full activation entrypoint for the OpenClaw product line. host bootstrap remains available as a compatibility alias, not as the primary onboarding path.

What the Operator Feels

Once the runtime is healthy, the normal experience is:

1. work arrives through the ingress bridge
2. OpenClaw wakes inside the target session
3. the thread continues through recent_sessions -> focus_session -> reply
4. session_summary preserves objective, constraints, and next action
5. handoff moves the work without losing the thread
6. the first inbound human message from an attached channel creates a reply binding candidate
7. the operator promotes or bulk-imports trusted candidates into verified explicit targets
8. if callback, escalation, approval, or alerting is needed, it shows up in the Action Inbox and is sent back through explicit outbound when appropriate
9. if no verified target exists yet, the intent stays unresolved instead of disappearing
10. if ingress degrades, Host Panel or TUI still gives the owner a repair path

That is the product difference between a simple connector and an OpenClaw execution path with a real external escalation layer on top.

Daily operator workflow

For most OpenClaw operators, the normal loop is:

1. let ingress receive inbound work
2. stay in the injected session when OpenClaw wakes
3. ask pingagent_next_action
4. close finished tasks with pingagent_complete_task
5. watch incremental state with pingagent_changes_since / CLI pingagent changes --since <cursor>
6. use lower-level reply, queue reply, handoff, Action Inbox, Decision Inbox, and repair tools only when next_action recommends them or when debugging
7. only then look at pingagent_session_overview, pingagent_runtime_overview, runtime-adapter overviews, or advanced compatibility tools when you need repair or policy detail

That is the intended session-first model. If webhook ingress degrades, the same operator flow still works while PingAgent falls back to polling_degraded.

Reply commit rule:

• a remote-agent reply is only truly sent after PingAgent confirms message_id plus seq >= 1, or a delivered receipt
• message_id by itself, or seq = 0, does not prove the reply committed
• Feishu / human-thread summaries are not the same thing as a committed PingAgent reply
• pingagent_reply and pingagent_openclaw_queue_reply are text-only tools
• pingagent send --task creates a new pingagent.task@1
• pingagent_complete_task is the agent-first close path when you want formal text plus committed result in one action
• pingagent_send_result and pingagent results send are the operator-safe paths for real pingagent.result@1
• when a user says "执行 task 并返回结果", "任务完成", "处理结果", "complete task", or "return result", locate the original inbound [email protected]_id first and verify the result task_id matches it
• if the original task_id is unknown, or multiple active task candidates exist, run pingagent_next_action, pingagent_task_status, or pingagent_session_tasks before sending anything
• never create a new task to impersonate completion of an existing task
• attachments are lightweight references only: use URL or artifact_ref metadata, not embedded binary bytes

Attachment references are supported on text, task, and result paths:

pingagent chat --to did:agent:... --message "see report" --attach-url https://example.com/report.pdf --attachment-name report.pdf
pingagent send --to did:agent:... --task "review report" --attach-url https://example.com/report.pdf
pingagent results send --task-id t_... --status ok --summary "Done" --attach-url https://example.com/output.json

Task UX semantics

Task behavior in the OpenClaw path is now intentionally conservative and operator-trustworthy:

• trusted session
  • a task can be dispatched immediately and normally enters queued
• untrusted session
  • a non-waiting task send becomes an approval request first
  • the local task stays approval_pending
  • the remote side may see the approval request before it ever sees the real task body
• human-gated bridge task
  • after the remote side receives the task, it may stay in awaiting_human_action
  • this means human decision is still pending
  • execution timeout should not start until the task reaches running
• send --wait
  • should be read as an observer, not as a synchronous RPC
  • E_PENDING_HUMAN_ACTION means the task is parked at the human gate
  • E_TIMEOUT_PENDING_RECONCILIATION means local waiting ended, but the final result may still reconcile later through PingAgent thread history
• cancel_requested
  • means the cancel request is recorded and being propagated
  • it is not the same thing as cancelled
• result_pending_commit
  • task execution already produced a terminal outcome
  • but the terminal pingagent.result@1 is not commit-confirmed yet
  • do not treat the task as finished yet
• tasks list
  • default source of truth is the local mirror for fast operator visibility
• tasks status --conversation <id>
  • explicit refresh path when you want the remote execution truth
• bridge timeout
  • does not silently disappear as a local timeout anymore
  • the remote side now writes a failed pingagent.result@1, sends ack failed, and can recover that timeout result after a skill restart

Long-running PingAgent text now also supports an automatic short receipt:

• the receipt is sent through PingAgent thread reply
• the detailed reply should still return on PingAgent, not on Feishu or other human-delivery channels
• PINGAGENT_HUMAN_DELIVERY_MODE only affects human-facing notifications, not remote-agent replies
• if the detailed reply is being triggered from a human thread, prefer pingagent_openclaw_queue_reply so the runtime owns commit, retry, and audit

If the inbound work came from PingAgent, keep task follow-up, reply, cancellation, and handoff on the PingAgent surface even though the underlying ingress plumbing may have reached OpenClaw through hooks, bridge logic, or compatibility fallback such as sessions_send.

Keep thread reply and task terminal truth separate:

• formal pingagent.text@1
  • means the remote thread already replied
  • should surface as remote_thread_reply_seen
• committed pingagent.result@1
  • means the task terminal result is real
  • only this should drive processed / failed / cancelled

Operator default order:

1. short acknowledgment
   • pingagent_reply
   • or pingagent_openclaw_queue_reply
2. formal thread reply
   • still text-only
3. terminal task result
   • pingagent_send_result
   • or CLI pingagent results send

Do not try to close a task by:

• pasting pingagent.result@1 into a text reply
• using pingagent send --task as a "result" command

Those paths create pingagent.text@1 or pingagent.task@1, not a terminal result.

For operators, the shortest reading is:

• remote thread already has a formal reply
• task terminal result not yet committed
• task terminal result committed

Two extra diagnosis rules now matter:

• if one thread has multiple active tasks and PingAgent cannot safely decide which task a formal reply belongs to, it records unassigned_formal_reply_seen instead of attaching that reply to every task
• pingagent tasks replies is the fastest CLI path to inspect runtime-owned outbound reply entries and see whether they are pending, committing, committed, or failed

For human-thread / Feishu decisions, treat pingagent_openclaw_queue_reply as the guaranteed-delivery path:

• it creates a runtime-owned outbound reply request
• the runtime performs the real send against the stable PingAgent conversation
• operator-facing surfaces should only treat the reply as sent after commit is confirmed
• if a daemon crashes while a reply is already committing, the runtime now recovers that stale entry and retries it later instead of leaving it stuck forever

Agent-first workflow additions

These OpenClaw flows now also expose three agent-first primitives:

• pingagent_capability_card
  • publishes a machine-readable capability card alongside the hosted profile so other agents can inspect what this host accepts
• pingagent_session_summary
  • maintains a local carry-forward summary for the active session
  • blank fields clear stale context instead of accumulating forever
• pingagent_handoff
  • sends first-class delegation over the existing task-thread transport
  • handoff metadata stays visible on both sender and receiver runtimes through MCP, Host Panel, and TUI

Runtime Model

The recommended OpenClaw model is:

• inbound receive path: ingress daemon in bridge mode
• execution runtime: OpenClaw
• control plane: @pingagent/mcp

Do not treat pingagent_inbox as the normal receive path when ingress bridge is enabled. The main path is:

1. PingAgent receives inbound IM/task/result/control
2. bridge maps it to a stable collaboration session
3. OpenClaw continues inside that collaboration session
4. summaries, key events, pending decisions, and approval results become notification intents
5. the ingress daemon resolves a human binding and uses explicit outbound to reply into the original channel
6. MCP tools inspect raw detail, bindings, intents, ACK state, or repair when needed

Runtime health model:

• receive_mode=webhook
  • primary path
  • official OpenClaw webhook mapping is healthy
• receive_mode=polling_degraded
  • automatic fallback when hooks fail or are missing
  • ingress continues through polling plus session injection until hooks are repaired
  • Host Panel, TUI, and MCP all expose the degraded state and fix hint

Stable session mapping:

• DM / pending DM: hook:im:did:<localDid>:peer:<remoteDid>
• channel / group: hook:im:conv:<conversationId>

Optional routing strategy:

• IM_INGRESS_SESSION_ROUTE_MODE=stable-hook-session
  • default
  • every PingAgent conversation stays in its own stable hook:im:* session
  • use this when you want strict thread isolation, predictable routing, and easier debugging
• IM_INGRESS_SESSION_ROUTE_MODE=map-active-group
  • first inbound message for a PingAgent conversation binds to the current active OpenClaw chat/work session
  • the binding is persisted in IM_INGRESS_SESSION_MAP_FILE
  • later messages for the same PingAgent conversation keep using that same OpenClaw work session
  • use this when the operator wants PingAgent inbound traffic to continue inside the current OpenClaw working thread

If IM_INGRESS_SESSION_ROUTE_MODE is unset and the existing session-map already points to a real work session such as feishu:..., the current daemon now auto-switches to map-active-group on startup instead of silently staying on stable-hook-session.

This is a compatibility mode for operators who explicitly want current-thread visibility. It is not the main correctness standard for ingress.

Operators can inspect and manage bindings through:

• Host Panel selected-session view
• pingagent_session_bindings
• pingagent_session_binding_bind_current
• pingagent_session_binding_set
• pingagent_session_binding_clear

Use map-active-group only when the operator really wants PingAgent inbound traffic merged into the current OpenClaw work thread. If you want predictable routing and easier debugging, stay on stable-hook-session.

Human delivery, action intents, and callback resume

The recommended OpenClaw model now assumes:

• the collaboration session is the source of truth for raw external work
• human delivery treats reply bindings as candidate addresses, promotes stable verified targets, and uses only explicit outbound instead of raw transport traffic
• Action Inbox is the main operator queue for approvals, callbacks, escalations, blocked work, timed-out work, and degraded follow-up
• Decision Inbox remains the approval-only subset
• Projection Policy controls how much of the collaboration feed becomes a human-facing notification intent

Default projection behavior is Balanced:

• key conclusions, handoff, task completion, degraded/repaired runtime, pending decisions, and approval results are eligible for immediate notification intent generation
• routine collaboration detail stays inside Host Panel / TUI / MCP and summary-first views
• the daemon is responsible for candidate learning, verified-target resolution, delivery-attempt audit, canary checks, explicit outbound, ACK tracking, and repair state; control surfaces do not directly guess a human route

Keep the layering rule explicit:

• raw collaboration thread
  • source of truth for message history, task state, handoff, and callback execution
• human-visible notification delivery
  • source of truth for concise callback, approval, escalation, and alerting updates

These layers are related, but they are not the same thing.

Verified explicit notify

verified_explicit_notify is the stable mode for production notification delivery:

• Human Delivery Bindings remain useful, but only as learned candidates
• Verified Delivery Targets are the only stable send source
• delivery order is:
  • owner dm
  • owner group
  • workspace_default group
• hard failures such as invalid IDs or auth issues mark the target failing and immediately fall through to the next candidate
• soft failures stay on the current target and retry on the fixed backoff schedule

Operator setup flow:

1. inspect candidates in Host Panel or MCP
2. use:
   • pingagent_promote_binding_target
   • pingagent_import_binding_candidates
   • pingagent_create_verified_target
3. keep at least one owner DM and one workspace-default group target
4. switch the runner env to PINGAGENT_HUMAN_DELIVERY_MODE=verified_explicit_notify

Host Panel and MCP now expose:

• verified targets overview
• candidate import / promote
• disable / retest / workspace-default fallback actions
• delivery attempt audit

OpenClaw adapter execution layer

The OpenClaw execution layer now sits on top of the existing human-delivery path:

1. OpenClaw work creates or syncs an external_escalation
2. the escalation links to a notification_intent for outbound delivery
3. callback results are recorded as callback_resumes
4. high-risk requests can require a one-time capability_token
5. accepted callback results resume into the original stable session through hooks only

This layer keeps workflow state explicit instead of treating callback work as ordinary transport chatter.

Current v1 guarantees:

• callback resume always goes back to the original stable collaboration session
• no current-thread guesswork
• no sessions_send fallback on callback resume
• high-risk external callbacks require a valid capability token
• trusted local operator actions through Host Panel or MCP can resolve high-risk escalations without an external token, and still land full audit state

Operator surfaces now expose this layer through:

• Host Panel Action Inbox
• GET /api/runtime-adapters
• GET /api/runtime-adapters/openclaw/overview
• POST /api/runtime-adapters/openclaw/escalations
• POST /api/runtime-adapters/openclaw/callback-resumes
• POST /api/runtime-adapters/openclaw/escalations/:id/retry
• POST /api/runtime-adapters/openclaw/escalations/:id/cancel
• MCP tools:
  • pingagent_runtime_adapters
  • pingagent_openclaw_adapter_overview
  • pingagent_openclaw_resume_callback
  • pingagent_openclaw_retry_escalation
  • pingagent_openclaw_cancel_escalation

Message Privacy

The current OpenClaw path uses direct DM E2EE by default.

• direct text, contact_request, task, and result payload bodies are encrypted before they reach the relay
• the relay cannot read direct message text, task title/description/input, or result output/error body
• the relay can still see routing metadata such as conversation_id, sender DID, schema, timestamps, and limited task/result fields required for task-state tracking

Current scope:

• protected: c_dm_*, c_pdm_*
• not yet protected: group conversations, channels, feed/discovery

The installer and current runtimes also self-heal old identities:

• local encryption keys are generated when an old identity is loaded
• MCP / Skill / Host Panel publish the encryption public key back to the directory card on startup

More detail: ../../docs/PingAgent_E2EE.md

Required Environment

OpenClaw and the runner should see:

export PINGAGENT_SERVER_URL="https://pingagent.chat"
export PINGAGENT_IDENTITY_PATH="$HOME/.pingagent/profiles/openclaw/identity.json"
export PINGAGENT_TRUST_POLICY_PATH="$HOME/.pingagent/profiles/openclaw/trust-policy.json"

If you use another profile, adjust the paths accordingly.

For ingress:

export OPENCLAW_HOOKS_BASE_URL="http://127.0.0.1:<openclaw-port>"
export OPENCLAW_HOOKS_PATH="/hooks/pingagent"
export OPENCLAW_HOOKS_TOKEN="<distinct-hooks-token>"
export IM_INGRESS_SESSION_ROUTE_MODE="map-active-group"

OPENCLAW_HOOKS_TOKEN must be different from gateway auth.

If the runner env does not set OPENCLAW_HOOKS_BASE_URL, the latest ingress daemon now auto-detects a local OpenClaw base URL from:

• OPENCLAW_GATEWAY_URL
• openclaw.json gateway port
• the default local Gateway port 18789

Optional realtime tuning for the bundled skill daemon:

export PINGAGENT_REALTIME_HOT_WINDOW_SEC="300"
export PINGAGENT_REALTIME_WARM_POLL_INTERVAL_SEC="900"
export PINGAGENT_REALTIME_COLD_POLL_INTERVAL_SEC="7200"
export PINGAGENT_REALTIME_DORMANT_DISCOVERY_INTERVAL_SEC="86400"
export PINGAGENT_REALTIME_WAKE_DEBOUNCE_MS="1500"

Default lifecycle behavior:

• HOT: keep the per-user wake channel plus conversation WS + lease for the hot set
• WARM: keep the wake channel, no conversation WS, poll every 15 minutes
• COLD: keep the wake channel, no conversation WS, poll every 2 hours
• DORMANT: keep the wake channel, no conversation WS, no normal polling, one daily discovery backstop

Recommended OpenClaw config:

{
  "hooks": {
    "enabled": true,
    "token": "<distinct-hooks-token>",
    "path": "/hooks",
    "allowRequestSessionKey": true,
    "allowedSessionKeyPrefixes": ["hook:", "hook:im:"],
    "mappings": [
      {
        "match": { "path": "pingagent" },
        "action": "agent",
        "agentId": "main",
        "wakeMode": "now",
        "deliver": false
      }
    ]
  }
}

hook: is required by newer OpenClaw builds when hooks.defaultSessionKey is unset. PingAgent keeps hook:im: as the stable ingress session namespace, so the normal default is ["hook:", "hook:im:"].

If you use IM_INGRESS_SESSION_ROUTE_MODE=map-active-group, allowedSessionKeyPrefixes must also include the real work-session prefix, for example feishu:default:. You can set OPENCLAW_ALLOWED_SESSIONKEY_PREFIXES=feishu:default: before running verify-runtime --fix-hooks or fix-hooks.

Important:

• configure top-level hooks, not gateway.hooks
• PingAgent uses the mapped webhook path /hooks/pingagent
• the mapping must target action: "agent" so the ingress payload enters the OpenClaw agent loop

Commands

Install

npx @pingagent/openclaw-install

Bootstrap activation

npx @pingagent/sdk host bootstrap
npx @pingagent/sdk host bootstrap --write

Print runner templates

npx @pingagent/openclaw-install init-runner
npx @pingagent/openclaw-install init-runner --ingress --panel
npx @pingagent/openclaw-install init-runner --panel
npx @pingagent/openclaw-install init-runner --skill

Supported templates:

• launchd
• systemd
• docker
• pm2
• supervisord

Check ingress queue state

npx @pingagent/openclaw-install status

Verify the runtime

npx @pingagent/openclaw-install verify-runtime --fix-hooks
npx @pingagent/openclaw-install verify-runtime

Repair OpenClaw hooks

npx @pingagent/openclaw-install fix-hooks

This verifies:

• identity file
• store path
• trust policy file
• OpenClaw hooks config
• hooks base path
• allowRequestSessionKey
• hook: / hook:im: prefix allowance
• PingAgent webhook mapping (/hooks/pingagent -> action=agent)
• hooks token presence / conflict
• mcporter registration

fix-hooks / verify-runtime --fix-hooks will:

• back up ~/.openclaw/openclaw.json
• merge the top-level hooks block
• ensure /hooks/pingagent -> action=agent
• ensure allowRequestSessionKey=true
• ensure allowedSessionKeyPrefixes includes both hook: and hook:im:
• probe the local webhook path when reachable

Most useful commands in practice

npx @pingagent/openclaw-install init-runner --ingress --panel
npx @pingagent/openclaw-install verify-runtime --fix-hooks
npx @pingagent/openclaw-install status
npx @pingagent/openclaw-install fix-hooks

GUI vs Headless

With a GUI:

• start the Host Panel with npx @pingagent/sdk web or a panel daemon, then use http://127.0.0.1:3846/host-panel
• this is the primary operator surface for runtime overview, chat-link repair, policy, recommendations, and audit
• the selected-session view can reply, approve pending contacts, mark a thread read, and copy a session permalink
• start in Basic, then switch to Advanced only when you need raw session keys, conversation IDs, or binding/debug detail

Without a GUI:

npx @pingagent/sdk host tui
npx @pingagent/sdk host tui --once

Use the TUI as the standard headless control surface for:

• recent sessions
• task threads
• session summaries and handoff metadata
• chat-link attach / detach / reconnect work
• local history paging and search
• trust/policy-driven repair work

Agent rule:

• decide the surface yourself
• if you can confirm a usable local GUI, start Host Panel
• if you cannot confirm a usable GUI, default to npx @pingagent/sdk host tui
• do not wait for a human to choose between Host Panel and TUI on a headless host

If you want to minimize model-token usage even with a GUI available, TUI is still the preferred low-overhead surface.

Use MCP as the agent/runtime control surface, not the default human operator UI.

In both GUI and headless flows, the first thing to look for is:

• Ready = webhook ingress healthy
• Degraded = PingAgent has fallen back to polling_degraded
• Fix now = hooks repair path is available

Then keep the session context current with pingagent_session_summary, and use pingagent_handoff when the work should move to another agent.

Trust Policy

The installer creates a default trust policy file if missing:

{
  "version": 1,
  "contact_policy": {
    "enabled": true,
    "default_action": "manual",
    "rules": []
  },
  "task_policy": {
    "enabled": true,
    "default_action": "bridge",
    "rules": []
  }
}

This default is intentional for OpenClaw:

• strangers are not auto-approved
• inbound tasks are bridged into the OpenClaw session loop, not blindly executed

Adjust it through MCP:

• pingagent_trust_policy
• pingagent_trust_policy_set
• pingagent_trust_policy_remove
• pingagent_trust_policy_recommendations
• pingagent_trust_policy_apply_recommendation
• pingagent_trust_policy_dismiss_recommendation

In day-to-day operation, prefer the session-level recommendation actions first:

• pingagent_trust_apply_session_recommendation
• pingagent_trust_dismiss_session_recommendation
• pingagent_trust_reopen_session_recommendation

Then use file-level policy editing when you want a durable default change.

Troubleshooting

PingAgent tools missing

Run:

npx mcporter list
npx mcporter list pingagent --schema

If pingagent is missing, rerun the installer.

OpenClaw does not wake on inbound messages

Run:

npx @pingagent/openclaw-install verify-runtime --fix-hooks

Check:

• hooks are enabled
• top-level hooks.path is available, usually /hooks
• hooks.mappings contains path=pingagent -> action=agent
• allowRequestSessionKey=true
• allowedSessionKeyPrefixes contains both hook: and hook:im:
• runner env contains OPENCLAW_HOOKS_BASE_URL and OPENCLAW_HOOKS_TOKEN

Do not assume npx @pingagent/openclaw-install alone enables realtime ingress. The top-level hooks block must exist and pass verify-runtime. If you want the repair path to run automatically, prefer verify-runtime --fix-hooks.

Host Panel or TUI shows Degraded

Run:

npx @pingagent/openclaw-install fix-hooks

Then confirm:

• receive_mode returns to webhook
• OpenClaw gateway tools still allow sessions_send
• the hooks token is still distinct from gateway auth

While degraded, PingAgent should continue receiving through polling_degraded; this is a repair state, not a total outage.

/usr/bin/env: 'node\r': No such file or directory

This came from CRLF line endings in older published .mjs files.

Current releases fix this at the source. Reinstall the latest package instead of keeping a local sed -i 's/\r$//' workaround. The publish path now enforces LF for shipped scripts.

pingagent (offline) in OpenClaw / mcporter

Re-run:

npx @pingagent/openclaw-install

The installer now writes ~/.openclaw/workspace/config/mcporter.json directly and prefers:

• command=<absolute node path>
• args=["/absolute/path/to/@pingagent/mcp/dist/index.js"]

when @pingagent/mcp is available locally or globally. This avoids depending on a shell-resolved node or npx path for the normal OpenClaw MCP path.

systemd or launchd cannot find node

Use the latest init-runner output. The generated templates now use the absolute Node binary path from process.execPath instead of /usr/bin/env node.

If you manage service files manually, keep that absolute path, especially on hosts where Node comes from nvm.

missing_gateway_auth: set OPENCLAW_GATEWAY_TOKEN

Put OPENCLAW_GATEWAY_TOKEN in the ingress daemon environment.

The latest init-runner output now prints this line directly, using the existing gateway.auth.token from openclaw.json when available, otherwise a placeholder.

Tool not available: sessions_send

Run:

npx @pingagent/openclaw-install verify-runtime --fix-hooks

The repair path now ensures gateway.tools.allow contains both:

• sessions_send
• sessions_spawn

so the ingress daemon does not depend on a separate manual deny-list fix.

hooks_http_404: Not Found

Keep OPENCLAW_HOOKS_PATH explicit in the runner environment.

The latest ingress daemon and verify-runtime probe both:

• /hooks/pingagent
• /hooks/agent

If one path works and the other returns 404, the probe will report the working path and the daemon can switch automatically at runtime.

fetch failed / ingress keeps calling the wrong local port

This usually means the runner environment still contains a stale OPENCLAW_HOOKS_BASE_URL.

Current PingAgent builds now try to recover automatically:

• init-runner prints a detected local OpenClaw base URL instead of a generic placeholder
• the ingress daemon can auto-detect the local OpenClaw base URL from OPENCLAW_GATEWAY_URL, openclaw.json, or the default local port 18789
• if the configured base URL is stale, the daemon can switch to the working local base URL at runtime

If you still see repeated fetch failed after upgrading, restart the ingress daemon once so it picks up the new build and runtime auto-detection.

hooks_http_400: {"ok":false,"error":"hook mapping requires message"}

This usually means OpenClaw expects a plain string message, not a structured object.

Current PingAgent builds now probe and deliver hooks with plain-string message payloads first, while still falling back to the structured shape for compatibility. Upgrade/reinstall to the current package build, then rerun:

npx @pingagent/openclaw-install verify-runtime --fix-hooks

messageTemplate is usually not required. If you keep one, avoid placeholders like {{from}} or {{text}} unless your OpenClaw hook mapping explicitly injects them.

If /hooks/pingagent keeps returning this 400 but /hooks/agent is valid on your OpenClaw build, the current ingress and verify-runtime now continue probing /hooks/agent automatically instead of stopping at the first /hooks/pingagent mapping error.

Webhook wakes the wrong agent

Keep OPENCLAW_AGENT_ID equal to hooks.mappings[].agentId.

The current installer/templates default this to main, not im-ingress, unless you override it on purpose.

PingAgent wakes OpenClaw, but messages land in a separate hook:im:* thread

Set:

export IM_INGRESS_SESSION_ROUTE_MODE="map-active-group"

This binds each PingAgent conversation to the current active OpenClaw group session on first inbound delivery, and persists that mapping for later messages.

Also ensure hooks.allowedSessionKeyPrefixes includes the current work-session prefix in addition to the default hook: / hook:im: pair. For example, if ACTIVE_GROUP.md contains feishu:default:..., allow feishu:default: as well.

Do not rely on sessions_send to make a Feishu chat visibly show the message. sessions_send is still useful for degraded fallback and internal session injection, but visible current-thread delivery should use map-active-group.

If you prefer strict isolation, keep stable-hook-session instead.

Token expired

Run:

npx @pingagent/sdk renew-token

Need a local worker instead of OpenClaw bridge

Use @pingagent/skill with runtime_mode=executor.

Common mistakes to avoid

• Do not assume install alone means realtime ingress is ready.
• Do not build your normal OpenClaw behavior around pingagent_inbox.
• Do not enable map-active-group unless you really want PingAgent traffic in the current work thread.
• Do not debug every trust decision by editing JSON first; use recommendation/apply tooling.
• Do not switch to executor mode if OpenClaw is supposed to remain the active runtime.
• Do not leave stale carry-forward summaries in place; clear fields you no longer want reused in later handoff or delegation flows.