Arnike/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d47b4da655d5769abd5d34fdbdd088716797a7f2
paperclip/packages/adapters/openclaw-gateway
T
History
Ismaël O. 3b7c42be86 fix(openclaw-gateway): complete and stabilize OpenClaw Gateway integration (#2322) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The `openclaw_gateway` adapter is how operators wire Paperclip
agents to an OpenClaw gateway over WebSocket
> - The adapter UI previously only exposed a handful of config fields in
edit mode; many timeout / auth / session-routing knobs were unreachable
through the form
> - The serializer also forgot to inject the configured `authToken` into
the `x-openclaw-token` header, and the server-side execute path lacked
retries on transient gateway errors and an `OPENCLAW_TOKEN` env fallback
> - This pull request exposes the full set of config fields in both
create and edit modes, fixes the serializer, hardens the server-side
execute path, and pins the existing default request timeouts (120s /
120000ms) — see the dedicated commit and the new unit tests
> - The benefit is operators can configure and reconfigure an
`openclaw_gateway` agent end-to-end through the UI, with no silent
change to the defaults documented in the adapter README and
`doc/ONBOARDING_AND_TEST_PLAN.md`

## Linked Issues or Issue Description

Closes #414
Closes #1901
Closes #2309

## What Changed

- **UI**: Removed the `!isCreate` guard so all `openclaw_gateway` config
fields are visible in both create and edit modes (`authToken`,
`agentId`, `sessionKeyStrategy`, `sessionKey`, `timeoutSec`,
`waitTimeoutMs`, `disableDeviceAuth`, `autoPairOnFirstConnect`, `role`,
`scopes`, `paperclipApiUrl`, `headersJson`, `payloadTemplate`,
`runtimeServices`).
- **Serialization**
(`packages/adapters/openclaw-gateway/src/ui/build-config.ts`): inject
`authToken` into headers as `x-openclaw-token`; apply safe defaults on
create (`timeoutSec=120`, `waitTimeoutMs=120000`,
`sessionKeyStrategy="issue"`, `role="operator"`,
`scopes=["operator.admin"]`).
- **Backend**
(`packages/adapters/openclaw-gateway/src/server/execute.ts`): add
`OPENCLAW_TOKEN` env-var fallback for `authToken`, retry logic (max 2
retries with backoff for transient gateway errors), session-key prefix
`agent:{agentId}:{sessionId}` when `agentId` is configured.
- **Defaults restoration** (dedicated commit): an earlier revision of
this PR lowered the default request timeouts to `60` / `30000`. The
current branch restores the historical `timeoutSec=120` /
`waitTimeoutMs=120000` defaults that match the values documented in
`packages/adapters/openclaw-gateway/src/index.ts`,
`src/server/execute.ts` on master, and the worked example in
`doc/ONBOARDING_AND_TEST_PLAN.md`.
- **Tests** (new):
`packages/adapters/openclaw-gateway/src/ui/build-config.test.ts` pins
the documented timeout and identity defaults so the silent-halve
regression cannot recur.

## Verification

- `pnpm --filter @paperclipai/adapter-openclaw-gateway typecheck`
- `pnpm typecheck` (root)
- Manual: create a new `openclaw_gateway` agent — all fields visible,
defaults populate as documented.
- Manual: edit an existing `openclaw_gateway` agent — every field
round-trips correctly and saves.
- Manual: unset `authToken` in the form and set `OPENCLAW_TOKEN` env var
— adapter picks up the env-var fallback.
- Manual: simulate a transient gateway error — execute retries up to 2
times with backoff before failing.

## Risks

- Low risk. Surface area is one adapter, behind explicit operator
configuration. The defaults change in this PR is a restoration of values
that already exist on master and in the adapter docs, so no production
agent sees a behavioral shift relative to the prior release. Field
exposure in edit mode is purely additive — existing values are preserved
on save.

## Model Used

- Provider/model: Claude (Anthropic) — `claude-opus-4-7`
- Mode: standard tool use, no extended thinking
- Capability notes: code execution + repository file edits via Claude
Code

## Cross-references and status (maintainer)

Closes #414
Closes #1901
Closes #2309

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip Bot <bot@paperclip.dev>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-06-11 23:31:39 -07:00
..
doc
Introduce bind presets for deployment setup
2026-04-11 07:09:07 -05:00
src
fix(openclaw-gateway): complete and stabilize OpenClaw Gateway integration (#2322)
2026-06-11 23:31:39 -07:00
CHANGELOG.md
chore: release v0.3.1
2026-03-12 13:09:22 -05:00
package.json
fix: add npm provenance package metadata
2026-03-17 16:01:48 -05:00
README.md
PAPA-430: workspace finalize gates + no-remote-git enforcement (#6969)
2026-05-29 08:25:29 -07:00
tsconfig.json
Fix root TypeScript solution config
2026-03-09 14:09:30 -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.

Reference in New Issue View Git Blame Copy Permalink