@pingagent/openclaw-install

One-command install of PingAgent Skill for OpenClaw without cloning the repo.

Usage

npx @pingagent/openclaw-install

Quickest path checklist

1. Run the installer (once on the OpenClaw host):

   npx @pingagent/openclaw-install

2. Set env vars in the environment where OpenClaw (and mcporter) run:

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

   (If you used a custom profile, adjust the path accordingly. For systemd/Docker, set these in the service config.)
3. Verify mcporter + PingAgent from a terminal:

   npx mcporter list
   npx mcporter list pingagent --schema
   npx mcporter call pingagent.pingagent_whoami

   You should see your PingAgent DID and basic status.
4. Restart OpenClaw, then in an OpenClaw chat say something like “查一下我的 PingAgent DID / who am I via PingAgent”，and let the agent use the PingAgent tools via mcporter call.

Requires Node.js ≥18. The script will:

1. Write/merge ~/.openclaw/openclaw.json with skills.entries.pingagent (enabled + default server URL). No MCP keys are written to config.
2. Copy the bundled PingAgent skill to ~/.openclaw/skills/pingagent (exec-based: agent calls tools via npx mcporter call pingagent.<tool> ...).
3. Install mcporter if needed and register PingAgent MCP: mcporter config add pingagent --command npx --args '["-y","@pingagent/mcp"]'.
4. Initialize PingAgent identity. By default, the installer uses profile openclaw and stores identity under ~/.pingagent/profiles/openclaw/identity.json. You can override the profile by setting PINGAGENT_PROFILE before running the installer (or by manually running PINGAGENT_PROFILE=<name> npx @pingagent/sdk init --server https://pingagent.chat).

Then set environment variables so OpenClaw (and mcporter) can see them: PINGAGENT_SERVER_URL, PINGAGENT_IDENTITY_PATH. Restart OpenClaw and use PingAgent in chat.

Troubleshooting

"Unrecognized key: mcp" / "Unrecognized key: mcpServers" / "Unrecognized key: agents.defaults.mcp"

This config does not support mcp, root-level mcpServers, or agents.defaults.mcp. Re-run npx @pingagent/openclaw-install; the script removes these keys and only writes skills.entries.pingagent. You can also delete the mcp block under agents.defaults manually in ~/.openclaw/openclaw.json.

"Unknown config keys: skills.entries.pingagent.mcp"

skills.entries only allow enabled, apiKey, and env. Do not put an mcp block inside the skill entry. Re-run the installer to fix.

PingAgent tools not available or empty output in OpenClaw

This package uses the mcporter + exec-based skill approach (OpenClaw’s recommended path; MCP is not written to openclaw.json). If the agent cannot use PingAgent tools or calls return nothing:

1. Run npx mcporter list — you should see pingagent. If not, run the installer again or manually: npx mcporter config add pingagent --command npx --args '["-y","@pingagent/mcp"]'.
2. Run npx mcporter list pingagent --schema to see tool names and parameters.
3. Ensure PINGAGENT_SERVER_URL and PINGAGENT_IDENTITY_PATH are set in the environment where OpenClaw (and mcporter) run (e.g. systemd, Docker, or your shell before starting OpenClaw).
4. Test in a terminal: npx mcporter call pingagent.pingagent_whoami.

Polling and real-time (PingAgent inbox)

openclaw-pingagent-poller.mjs is deprecated. We no longer recommend spawning mcporter per poll; it starts a new process on each poll and is costly. For near-real-time messaging, use the PingAgent Skill daemon (long-lived process with in-process WebSocket + in-process API polling). See @pingagent/skill README for how to start the daemon. The daemon polls every 15 minutes (or on WebSocket reconnect) and, when the server returns last_activity_at per conversation, only fetches inbox for conversations with new activity—keeping request volume low. The MCP tools (pingagent_inbox, etc.) remain available for on-demand and occasional checks; when the Skill daemon is running, messages are delivered in real time via WebSocket.

Enabling a dedicated Skill runner (optional, recommended for real-time)

For OpenClaw hosts that want a dedicated PingAgent Skill runner (long-lived process that handles real-time inbox and tasks), you can:

1. Run the base installer (once per host):

   npx @pingagent/openclaw-install

2. Wire an OpenClaw runner to the bundled Skill daemon:

   npx @pingagent/openclaw-install init-runner

   This updates ~/.openclaw/openclaw.json and adds/updates:

   "runners": {
     "pingagent-runner": {
       "command": "node",
       "args": ["/path/to/node_modules/@pingagent/openclaw-install/skill-daemon.mjs"],
       "env": {
         "PINGAGENT_SERVER_URL": "https://pingagent.chat",
         "PINGAGENT_ROOT_DIR": "~/.pingagent",
         "PINGAGENT_PROFILE": "openclaw"
       }
     }
   }

3. In your OpenClaw runner configuration, reference pingagent-runner according to OpenClaw's docs, and ensure the environment where the runner starts can see the configured PINGAGENT_* variables (or override them as needed).

The skill-daemon.mjs entrypoint uses PingAgentSkill.start() + loadConfigFromEnv() and can be forked if you need a custom TaskExecutor; the bundled version uses a no-op executor that logs tasks but does not execute destructive actions.

Comparison with ClawHub

OpenClaw recommends installing skills via ClawHub: npx clawhub@latest install <skill-slug>. This package provides a similar one-command experience for PingAgent using mcporter + exec-based skill (MCP is not written to openclaw.json).

Publish

From repo root after building:

pnpm build
cd packages/openclaw-install && npm publish --access public

No build step is required for this package (plain ESM .mjs + skill/ folder).