RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/adapters/openclaw-gateway
History
dependabot[bot] ec8d7dd21f
build(deps): bump ws from 8.21.1 to 8.21.3 (#11729) 
Bumps [ws](https://github.com/websockets/ws) from 8.21.1 to 8.21.3.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/websockets/ws/releases">ws's
releases</a>.</em></p>
<blockquote>
<h2>8.21.3</h2>
<h1>Bug fixes</h1>
<ul>
<li>The server now correctly rejects permessage-deflate offers if the
incoming
<code>client_max_window_bits</code> parameter value is smaller than its
configured
<code>clientMaxWindowBits</code> (e97a20ea).</li>
</ul>
<h2>8.21.2</h2>
<h1>Bug fixes</h1>
<ul>
<li>Fixed a test for <a href="https://github.com/nodejs/citgm">CITGM</a>
(2eb3be0b).</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="c791e707ea"><code>c791e70</code></a>
[dist] 8.21.3</li>
<li><a
href="e97a20eaa6"><code>e97a20e</code></a>
[fix] Reject offers with <code>client_max_window_bits</code> below
config</li>
<li><a
href="787ebf22ce"><code>787ebf2</code></a>
[dist] 8.21.2</li>
<li><a
href="b4d62ebad4"><code>b4d62eb</code></a>
Revert &quot;[ci] Trust Coveralls Homebrew tap&quot;</li>
<li><a
href="e4bb883723"><code>e4bb883</code></a>
[security] Use GitHub PVR as main reporting channel</li>
<li><a
href="2eb3be0bff"><code>2eb3be0</code></a>
[test] Skip test on Node.js versions where it does not apply</li>
<li>See full diff in <a
href="https://github.com/websockets/ws/compare/8.21.1...8.21.3">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=ws&package-manager=npm_and_yarn&previous-version=8.21.1&new-version=8.21.3)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 		2026-08-19 10:30:13 -07:00
..
doc Introduce bind presets for deployment setup 2026-04-11 07:09:07 -05:00
src fix(openclaw-gateway): use per-agent claimedApiKeyPath in wake text (#4668) 2026-08-05 00:53:43 -05:00
CHANGELOG.md chore: release v0.3.1 2026-03-12 13:09:22 -05:00
README.md PAPA-430: workspace finalize gates + no-remote-git enforcement (#6969) 2026-05-29 08:25:29 -07:00
package.json build(deps): bump ws from 8.21.1 to 8.21.3 (#11729) 2026-08-19 10:30:13 -07:00
tsconfig.json Fix root TypeScript solution config 2026-03-09 14:09:30 -05:00
vitest.config.ts fix(openclaw-gateway): use per-agent claimedApiKeyPath in wake text (#4668) 2026-08-05 00:53:43 -05:00

README.md

OpenClaw Gateway Adapter

This document describes how @paperclipai/adapter-openclaw-gateway invokes OpenClaw over the Gateway protocol.

Transport

This adapter always uses WebSocket gateway transport.

  • URL must be ws:// or wss://
  • Connect flow follows gateway protocol:
  1. receive connect.challenge
  2. send req connect (protocol/client/auth/device payload)
  3. send req agent
  4. wait for completion via req agent.wait
  5. stream event agent frames into Paperclip logs/transcript parsing

Auth Modes

Gateway credentials can be provided in any of these ways:

  • authToken / token in adapter config
  • headers.x-openclaw-token
  • headers.x-openclaw-auth (legacy)
  • password (shared password mode)

When a token is present and authorization header is missing, the adapter derives Authorization: Bearer <token>.

Device Auth

By default the adapter sends a signed device payload in connect params.

  • set disableDeviceAuth=true to omit device signing
  • set devicePrivateKeyPem to pin a stable signing key
  • without devicePrivateKeyPem, the adapter generates an ephemeral Ed25519 keypair per run
  • when autoPairOnFirstConnect is enabled (default), the adapter handles one initial pairing required by calling device.pair.list + device.pair.approve over shared auth, then retries once.

Session Strategy

The adapter supports the same session routing model as HTTP OpenClaw mode:

  • sessionKeyStrategy=issue|fixed|run
  • sessionKey is used when strategy is fixed

Resolved session key is sent as agent.sessionKey.

Payload Mapping

The agent request is built as:

  • required fields:
    • message (wake text plus optional payloadTemplate.message/payloadTemplate.text prefix)
    • idempotencyKey (Paperclip runId)
    • sessionKey (resolved strategy)
  • optional additions:
    • all payloadTemplate fields merged in
    • agentId from config if set and not already in template

Timeouts

  • timeoutSec controls adapter-level request budget
  • waitTimeoutMs controls agent.wait.timeoutMs

If agent.wait returns timeout, adapter returns openclaw_gateway_wait_timeout.

Log Format

Structured gateway event logs use:

  • [openclaw-gateway] ... for lifecycle/system logs
  • [openclaw-gateway:event] run=<id> stream=<stream> data=<json> for event agent frames

UI/CLI parsers consume these lines to render transcript updates.

No-remote-git contract

Like every Paperclip adapter, this one must treat the local execution-workspace cwd as the only persistence boundary across runs — no git push from runtime code, no assuming a git remote exists. The gateway transport here doesn't touch the workspace directly, but if you extend the adapter to ship code to the OpenClaw side, use the round-trip helpers in @paperclipai/adapter-utils (prepareWorkspaceForSshExecution → restoreWorkspaceFromSshExecution) rather than reaching for a git remote. See packages/adapters/AUTHORING.md for the full contract and the pinning test at packages/adapter-utils/src/ssh-fixture.test.ts.