@kagura-agent/atlas-openclaw 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -14,7 +14,9 @@ In Atlas, choose **Connect AI tools → OpenClaw** from the account menu. The st
14
14
 
15
15
  Restart the OpenClaw gateway after installation. Atlas shows **Connected** when the authenticated socket connects. Select the connection and send a message.
16
16
 
17
- Use the public HTTPS Atlas origin when OpenClaw runs on another machine. Forward `/agent-worker` with WebSocket upgrades and `/api/agent-worker/` to the same Atlas server. HTTP is accepted only for loopback development, including an SSH tunnel. Do not expose a development HTTP port on the network.
17
+ Use the public HTTPS Atlas origin when OpenClaw runs on another machine. Forward `/agent-worker` with WebSocket upgrades and `/api/agent-worker/` to the same Atlas server. Loopback HTTP is supported for local development and SSH tunnels.
18
+
19
+ For development on a trusted LAN, set `channels.atlas.allowPrivateNetworkHttp` to `true` and use the Atlas machine's private IPv4 address in `baseUrl`, such as `http://10.172.208.53:4317`. Atlas must listen on its LAN interface, and the firewall must allow the OpenClaw machine to reach that port. This opt-in accepts only literal addresses in `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`; public HTTP and HTTP hostnames remain rejected. Keep the token private and use HTTPS outside the trusted LAN. The browser's Google callback address can stay on localhost.
18
20
 
19
21
  Tokens belong in OpenClaw's private configuration, never in messages, source files or shared installation snippets. Maintainer documentation (repository access required): [Connect agents](https://github.com/kagura-chen/atlas/blob/main/docs/product/AI-TOOLS.md#在画板中与-openclaw-对话) and [Current gaps](https://github.com/kagura-chen/atlas/blob/main/docs/CURRENT-GAPS.md).
20
22
 
@@ -38,7 +40,7 @@ Increase the committed package version before another release. An existing versi
38
40
 
39
41
  ## Design
40
42
 
41
- WebSocket notifications wake the worker; reconnecting and periodic server notifications refresh the queue. Finishing a run immediately checks for the next queued task. Short renewable run leases prevent a lost worker from silently reexecuting work. Tool writes use stable request IDs; canvas changes, run updates and receipts commit in the same SQLite transaction. Lost HTTP responses can be retried without duplicating writes. Final settlement is idempotent too.
43
+ WebSocket notifications wake the worker; reconnecting and periodic server notifications refresh the queue. If no server notification or ping arrives for 45 seconds, the plugin closes the stale socket and reconnects, including when a sleeping computer or a network interruption leaves TCP apparently open. Finishing a run immediately checks for the next queued task. Short renewable run leases prevent a lost worker from silently reexecuting work. Tool writes use stable request IDs; canvas changes, run updates and receipts commit in the same SQLite transaction. Lost HTTP responses can be retried without duplicating writes. Final settlement is idempotent too.
42
44
 
43
45
  Each turn gets a fresh OpenClaw session with Atlas's completed conversation history. Cancelled and failed prompts are excluded so runtime transcript replay cannot revive them. The runtime tool allowlist is `atlas_board`; tool instances exist only for the active run's session and cannot choose another board or acquire a new scope. Stop aborts the dispatcher; only after it returns does the plugin report settlement. OpenClaw error payloads are failures, not successful replies.
44
46
 
@@ -20,7 +20,12 @@
20
20
  "enabled": { "type": "boolean" },
21
21
  "baseUrl": { "type": "string" },
22
22
  "token": { "type": "string" },
23
- "agentId": { "type": "string" }
23
+ "agentId": { "type": "string" },
24
+ "allowPrivateNetworkHttp": {
25
+ "type": "boolean",
26
+ "default": false,
27
+ "description": "Allow HTTP to an explicit private IPv4 address on a trusted local network"
28
+ }
24
29
  }
25
30
  },
26
31
  "uiHints": { "token": { "sensitive": true } }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kagura-agent/atlas-openclaw",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Connect an external OpenClaw agent to Atlas conversations and canvas tools",
5
5
  "repository": {
6
6
  "type": "git",
package/worker.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { isIP } from "node:net";
2
3
  import { setTimeout as sleep } from "node:timers/promises";
3
4
  import WebSocket from "ws";
4
5
 
@@ -15,11 +16,20 @@ export function connection(account) {
15
16
  !["http:", "https:"].includes(base.protocol)
16
17
  )
17
18
  throw new Error("Atlas requires an HTTP(S) origin");
19
+ const [first, second] = base.hostname.split(".").map(Number);
20
+ const privateIpv4 =
21
+ isIP(base.hostname) === 4 &&
22
+ (first === 10 ||
23
+ (first === 172 && second >= 16 && second <= 31) ||
24
+ (first === 192 && second === 168));
18
25
  if (
19
26
  base.protocol === "http:" &&
20
- !["localhost", "127.0.0.1", "[::1]"].includes(base.hostname)
27
+ !["localhost", "127.0.0.1", "[::1]"].includes(base.hostname) &&
28
+ !(account.allowPrivateNetworkHttp === true && privateIpv4)
21
29
  )
22
- throw new Error("Use HTTPS for remote Atlas connections");
30
+ throw new Error(
31
+ "Use HTTPS, or enable allowPrivateNetworkHttp for a private IPv4 address",
32
+ );
23
33
  return base.origin;
24
34
  }
25
35
  export function client(account) {
@@ -283,7 +293,7 @@ export async function startAccount(ctx) {
283
293
  };
284
294
  const open = () => {
285
295
  if (ctx.abortSignal.aborted) return;
286
- socket = new WebSocket(
296
+ const ws = new WebSocket(
287
297
  connection(ctx.account).replace(/^http/, "ws") + "/agent-worker",
288
298
  {
289
299
  headers: { Authorization: `Bearer ${ctx.account.token}` },
@@ -291,7 +301,17 @@ export async function startAccount(ctx) {
291
301
  maxPayload: 65536,
292
302
  },
293
303
  );
294
- socket.on("open", () => {
304
+ socket = ws;
305
+ let inactivity;
306
+ const received = () => {
307
+ clearTimeout(inactivity);
308
+ // Atlas sends queue notifications every 10 seconds and pings every 20.
309
+ // A broken network path may leave TCP open without ever emitting close.
310
+ inactivity = setTimeout(() => ws.terminate(), 45000);
311
+ inactivity.unref?.();
312
+ };
313
+ ws.on("open", () => {
314
+ received();
295
315
  ctx.setStatus?.({
296
316
  accountId: ctx.accountId,
297
317
  connected: true,
@@ -299,15 +319,18 @@ export async function startAccount(ctx) {
299
319
  });
300
320
  void check();
301
321
  });
302
- socket.on("message", () => {
322
+ ws.on("ping", received);
323
+ ws.on("message", () => {
324
+ received();
303
325
  void check();
304
326
  });
305
- socket.on("error", () => {});
306
- socket.on("close", () => {
327
+ ws.on("error", () => {});
328
+ ws.on("close", () => {
329
+ clearTimeout(inactivity);
307
330
  ctx.setStatus?.({
308
331
  accountId: ctx.accountId,
309
332
  connected: false,
310
- running: true,
333
+ running: !ctx.abortSignal.aborted,
311
334
  });
312
335
  if (!ctx.abortSignal.aborted) reconnect = setTimeout(open, 3000);
313
336
  });