AgentTown Observer for OpenClaw

Read-only OpenClaw Gateway observer for AgentTown.

Install

openclaw plugins install ./openclaw-agenttown-observer
openclaw plugins enable agenttown-observer
openclaw gateway restart

Surfaces

• CLI:
  • agenttown connect --code-only
  • agenttown pair --code-only
  • agenttown relay-pair --code-only
  • agenttown relay
  • agenttown relay-status
  • agenttown service install --user <runtime-user>
  • agenttown service status|logs|restart|uninstall
  • agenttown configure --agenttown-token <token> --openclaw-token <token>
  • agenttown direct-pair --agenttown-url http://129.204.159.213:8787 --endpoint <AgentTown-can-reach-runtime-url> --code-only
  • agenttown status
  • agenttown update
  • agenttown openclaw-upgrade
• Tool: agenttown.status
• Tool: agenttown.inventory
• Tool: agenttown.pairing
• HTTP routes:
  • GET /agenttown/status
  • GET /agenttown/inventory
  • GET /agenttown/agents
  • GET /agenttown/skills
  • GET /agenttown/tools
  • GET /agenttown/commands
  • GET /agenttown/workflows
  • GET /agenttown/usage
  • GET /agenttown/cron
  • GET /agenttown/pairing?endpoint=http://127.0.0.1:18789&agenttownUrl=http://127.0.0.1:3000&allowLoopbackDirect=true
• Skill: agenttown-observer

All outputs are redacted and read-only.

agenttown connect --code-only is the normal first-time OpenClaw relay mode. It registers the runtime through /api/relay/register, prints a relay access code, and keeps the relay running in the foreground. After the App redeems the code once, run agenttown service install --user <runtime-user> so systemd keeps agenttown relay alive in the background after terminal, runtime, or machine restarts. Later agenttown connect runs reuse the saved relay identity by default and do not rotate the pairing code; use agenttown connect --new-code --code-only only when the App must pair again. The AgentTown App should redeem that code through /api/relay/redeem and call the runtime through /api/relay/rpc; it should not call http://127.0.0.1:18789 from the App machine. agenttown pair --code-only plus agenttown relay remains available as the explicit two-step flow.

agenttown.pairing and /agenttown/pairing are legacy direct descriptor surfaces. They register the sanitized agenttown.runtime_pairing.v1 descriptor with AgentTown only for networks where the App can directly reach the runtime endpoint. Loopback endpoints are rejected unless direct=true or allowLoopbackDirect=true is passed for local/tunnel testing. The descriptor contains only challengeId, codeHash, and expiresAt in its pairing block; it never contains the plaintext pairing code.

If the AgentTown pairing server requires a registration token, save it locally once before running agenttown connect:

agenttown configure --agenttown-token '<AgentTown pairing token>'

If OpenClaw Gateway requires auth for /agenttown/status, also save the OpenClaw token locally:

agenttown configure --openclaw-token '<OpenClaw token>'

Both values are stored only on the OpenClaw host under ~/.openclaw/plugins/agenttown-observer/data/auth.json with best-effort private file permissions. The App and pairing server do not receive the OpenClaw token. You can also use --openclaw-auth-header 'Header-Name: value' for non-Bearer auth.

Defaults:

• Pairing server: http://129.204.159.213:8787
• OpenClaw endpoint: auto-detected from common local Gateway ports, with http://127.0.0.1:18789 as the first candidate

Override with AGENTTOWN_PAIRING_SERVER_URL, AGENTTOWN_RUNTIME_ENDPOINT, --agenttown-url, or --endpoint only when networking requires it.

Update

agenttown update

This updates the global npm package, backs up old OpenClaw extension directories, reinstalls/enables agenttown-observer, and restarts the gateway. Use agenttown openclaw-upgrade when you want the explicit command name.