Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docker/platformclaw-runtime/OPERATIONS.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,27 @@ Compose config에는 숫자 설정만 표시된다. 별도 `docker compose exec
launcher가 계산한 옵션을 상속하지 않으므로 실제 Gateway 프로세스의
`NODE_OPTIONS`와 유효 heap limit으로 적용 여부를 확인한다.

Gateway의 heap 페이지가 스왑으로 밀리면 GC가 해당 페이지를 다시 읽는 동안 이벤트 루프가
수십 초 멈춰 관리 RPC가 시간 초과될 수 있다. Compose는 `mem_limit`와 `memswap_limit`에
`deployment.env`의 `PLATFORMCLAW_GATEWAY_MEM_LIMIT`를 동일하게 적용해 스왑을 막는다.
키가 없거나 비어 있으면 `16g`를 사용한다. 기본값은 old-space 8GiB에 Node의 기타 할당,
버퍼, 컨테이너 내 `ssh`·`sshpass` 프로세스용 여유 4GiB 이상을 더한 값이다. 나머지 공간에
들어간 파일 캐시는 메모리 압박 시 cgroup 안에서 회수된다. 한도는
`PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE`보다 최소 4GiB 높게 설정한다. Docker는 `0`을
한도 미설정으로 처리하며, 양의 한도가 너무 낮으면 스왑 없이 OOM kill이 발생할 수 있다.
`platformclaw-deploy up`, `image update`, `config apply`는
같은 Compose 설정을 사용하며 컨테이너를 재생성할 때 새 한도를 적용한다.

배포 후 cgroup v2와 systemd cgroup 드라이버를 사용하는 Docker 호스트에서 확인한다.

```bash
cat /sys/fs/cgroup/system.slice/docker-$(docker inspect -f '{{.Id}}' platformclaw-openclaw-gateway-1).scope/memory.swap.max
docker inspect -f '{{.HostConfig.Memory}} {{.HostConfig.MemorySwap}}' platformclaw-openclaw-gateway-1
```

첫 명령은 `0`을, 두 번째 명령은 같은 양의 바이트 값 두 개를 출력해야 한다. 기본값이면
두 값 모두 `17179869184`다.

secret 경로는 `~/platformclaw/secrets`를 가리킨다. `init`은 경로만 기록하며, 첫
새 설치의 첫 `up`은 PlatformClaw이 소유하는 Gateway/Knox/execution 계열의 누락 secret을
생성한다. 외부 시스템 credential은 자동 생성하지 않는다. 예를 들어 private S3 가이드의
Expand Down
4 changes: 4 additions & 0 deletions docker/platformclaw-runtime/compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ services:
openclaw-gateway:
image: ${PLATFORMCLAW_IMAGE:-platformclaw:local}
pull_policy: never
# 16 GiB budgets 8 GiB of old space plus at least 4 GiB for Node, buffers,
# and ssh/sshpass. The cgroup can reclaim file cache under pressure.
mem_limit: ${PLATFORMCLAW_GATEWAY_MEM_LIMIT:-16g}
memswap_limit: ${PLATFORMCLAW_GATEWAY_MEM_LIMIT:-16g} # Match mem_limit to disable swap.
user: "${PLATFORMCLAW_RUNTIME_UID:?run platformclaw-compose with a service user}:${PLATFORMCLAW_RUNTIME_GID:?run platformclaw-compose with a service user}"
depends_on:
platformclaw-state-init:
Expand Down
3 changes: 3 additions & 0 deletions docker/platformclaw-runtime/deployment.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox:<sha12>
# Gateway V8 old-space ceiling in MiB. This is not an RSS/container memory limit.
# The launcher appends this heap option to existing NODE_OPTIONS.
PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE=8192
# Keep the Gateway container limit at least 4 GiB above the old-space ceiling.
# Swap is disabled. A limit set too low can cause an OOM kill.
PLATFORMCLAW_GATEWAY_MEM_LIMIT=16g
# Composer Predictions model must name a configured provider/model.
PLATFORMCLAW_COMPOSER_PREDICTIONS_MODEL=codemate/codellm-fast
PLATFORMCLAW_SKILL_HUB_ENABLED=true
Expand Down
2 changes: 1 addition & 1 deletion docker/platformclaw-runtime/platformclaw-compose
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ skillhub_enabled="$(sed -n 's/^PLATFORMCLAW_SKILL_HUB_ENABLED=//p' "$PLATFORMCLA
# Stable deployment values come only from deployment.env. Ambient shell values
# must not silently override an image update, rollback, origin, or secret path.
unset PLATFORMCLAW_IMAGE PLATFORMCLAW_SANDBOX_IMAGE \
PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE \
PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE PLATFORMCLAW_GATEWAY_MEM_LIMIT \
PLATFORMCLAW_COMPOSER_PREDICTIONS_MODEL \
PLATFORMCLAW_PUBLIC_ORIGIN PLATFORMCLAW_PUBLIC_PORT PLATFORMCLAW_GUIDE_VIDEO_URL \
PLATFORMCLAW_GUIDE_VIDEO_S3_ENDPOINT PLATFORMCLAW_GUIDE_VIDEO_S3_REGION \
Expand Down
14 changes: 8 additions & 6 deletions scripts/generate-npm-package-lock.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -315,15 +315,17 @@ function resolvePnpmLockOverridePlan(lockfile) {
) {
continue;
}
// Hosted-source snapshots use a URL key, while npm matches the package's
// published semantic version when applying a scoped child policy.
const parentVersion = exactVersionFromOverrideSpec(
lockfile.packages?.[`${parent.name}@${parent.version}`]?.version ?? parent.version,
);
const parentPackage = lockfile.packages?.[`${parent.name}@${parent.version}`];
const parentVersion = exactVersionFromOverrideSpec(parentPackage?.version ?? parent.version);
if (!parentVersion) {
continue;
}
const parentSelector = `${parent.name}@${parentVersion}`;
// npm cannot match a versioned override to a Git commit edge. A name-only
// selector preserves the child pins when the parent has one locked source.
const parentSelector =
parentPackage?.resolution?.gitHosted === true && versionsByName.get(parent.name)?.size === 1
? parent.name
: `${parent.name}@${parentVersion}`;
for (const [dependencyName, dependencySpec] of Object.entries(dependencies)) {
if (!multiVersionPackageNames.has(dependencyName)) {
continue;
Expand Down
20 changes: 15 additions & 5 deletions test/scripts/generate-npm-package-lock.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -254,11 +254,11 @@ describe("generate-npm-package-lock", () => {
});
});

it("preserves decorated snapshot children under the hosted parent's actual package version", () => {
it("preserves decorated snapshot children for an unambiguous Git commit parent", () => {
const source = "https://codeload.github.com/example/acpx/tar.gz/reviewed";
const plan = resolvePnpmLockOverridePlan({
const lockfile = {
packages: {
[`acpx@${source}`]: { version: "0.13.2" },
[`acpx@${source}`]: { version: "0.13.2", resolution: { gitHosted: true } },
"@agentclientprotocol/sdk@1.3.0": {},
"@agentclientprotocol/sdk@1.4.0": {},
"zod@3.25.76": {},
Expand All @@ -278,16 +278,26 @@ describe("generate-npm-package-lock", () => {
dependencies: { zod: "3.25.76(patch_hash=other)" },
},
},
});
};
const plan = resolvePnpmLockOverridePlan(lockfile);
expect(plan.scopedVersionOverrides).toEqual({
"@agentclientprotocol/sdk@1.3.0": { zod: "3.25.76" },
"@agentclientprotocol/sdk@1.4.0": { zod: "4.6.6" },
"acpx@0.13.2": {
acpx: {
"@agentclientprotocol/sdk": { ".": "1.4.0", zod: "4.6.6" },
zod: "4.6.6",
},
});
expect(plan.versionOverrides).not.toHaveProperty("zod");

const ambiguous = resolvePnpmLockOverridePlan({
...lockfile,
packages: { ...lockfile.packages, "acpx@0.13.2": {} },
});
expect(ambiguous.scopedVersionOverrides).not.toHaveProperty("acpx");
expect(ambiguous.scopedVersionOverrides["acpx@0.13.2"]).toEqual(
plan.scopedVersionOverrides.acpx,
);
});

it("does not invent a semantic parent version for an unversioned hosted package", () => {
Expand Down
35 changes: 26 additions & 9 deletions test/scripts/platformclaw-gateway-heap.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ const runtimeRoot = path.resolve("docker/platformclaw-runtime");
const bash = process.platform === "win32" ? "C:/Program Files/Git/bin/bash.exe" : "bash";
const hasCompose = spawnSync("docker", ["compose", "version"], { stdio: "ignore" }).status === 0;
const heapKey = "PLATFORMCLAW_GATEWAY_MAX_OLD_SPACE_SIZE";
const memLimitKey = "PLATFORMCLAW_GATEWAY_MEM_LIMIT";

function shellPath(value: string): string {
return process.platform === "win32"
Expand Down Expand Up @@ -233,18 +234,19 @@ compose=(record_compose)
}
}, 30_000);

it("preserves a custom setting through the updater's image-pair update and rollback", () => {
it("preserves custom gateway limits through image-pair update and rollback", () => {
const root = tempDirs.make("platformclaw-heap-update-");
const functions = extractDeployFunctions("read_env_value", "set_image_pair");
const result = runShell(
`${functions}
deploy_root="$PLATFORMCLAW_TEST_ROOT"
env_file="$deploy_root/deployment.env"
for heap in 4096 8192 12288; do
printf '%s\\n' 'PLATFORMCLAW_IMAGE=platformclaw:old' 'PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox:old' "${heapKey}=$heap" >"$env_file"
printf '%s\\n' 'PLATFORMCLAW_IMAGE=platformclaw:old' 'PLATFORMCLAW_SANDBOX_IMAGE=platformclaw-sandbox:old' "${heapKey}=$heap" '${memLimitKey}=20g' >"$env_file"
cp "$env_file" "$env_file.previous"
set_image_pair platformclaw:new platformclaw-sandbox:new
[[ "$(read_env_value ${heapKey})" == "$heap" ]]
[[ "$(read_env_value ${memLimitKey})" == 20g ]]
[[ "$(read_env_value PLATFORMCLAW_IMAGE)" == platformclaw:new ]]
set_image_pair "$(read_env_value PLATFORMCLAW_IMAGE "$env_file.previous")" "$(read_env_value PLATFORMCLAW_SANDBOX_IMAGE "$env_file.previous")"
cmp "$env_file" "$env_file.previous"
Expand All @@ -254,9 +256,15 @@ done`,
expect(result.status, result.stderr || result.error?.message).toBe(0);
});

it.skipIf(!hasCompose).each([undefined, "", "4096", "8192", "12288"])(
"uses the deployment env value %j only for the gateway through Compose",
(heap) => {
it.skipIf(!hasCompose).each([
{ heap: undefined, memLimit: undefined, limitGiB: 16 },
{ heap: "", memLimit: "", limitGiB: 16 },
{ heap: "4096", memLimit: "12g", limitGiB: 12 },
{ heap: "8192", memLimit: "16g", limitGiB: 16 },
{ heap: "12288", memLimit: "20g", limitGiB: 20 },
])(
"renders gateway-only limits with heap $heap and memory $memLimit",
({ heap, memLimit, limitGiB }) => {
const root = tempDirs.make("platformclaw-heap-compose-");
const envFile = path.join(root, "deployment.env");
const secret = path.join(root, "synthetic-secret");
Expand All @@ -279,6 +287,7 @@ done`,
"SSH_CREDENTIAL_MASTER_KEY_SECRET_FILE",
].map((key) => `PLATFORMCLAW_${key}=${secret.replaceAll("\\", "/")}`),
...(heap === undefined ? [] : [`${heapKey}=${heap}`]),
...(memLimit === undefined ? [] : [`${memLimitKey}=${memLimit}`]),
];
writeFileSync(envFile, `${values.join("\n")}\n`);
const result = runShell(
Expand All @@ -293,6 +302,7 @@ exec bash "$PLATFORMCLAW_TEST_COMPOSE" config --format json
PLATFORMCLAW_DEPLOY_ROOT: shellPath(root),
PLATFORMCLAW_ENV_FILE: shellPath(envFile),
[heapKey]: "16384",
[memLimitKey]: "24g",
PLATFORMCLAW_GUIDE_VIDEO_URL: "",
PLATFORMCLAW_GUIDE_VIDEO_S3_ENDPOINT: "",
PLATFORMCLAW_GUIDE_VIDEO_S3_BUCKET: "",
Expand All @@ -306,16 +316,23 @@ exec bash "$PLATFORMCLAW_TEST_COMPOSE" config --format json
);
expect(result.status, result.stderr || result.error?.message).toBe(0);
const config = JSON.parse(result.stdout) as {
services: Record<string, { environment?: Record<string, string> }>;
services: Record<
string,
{ environment?: Record<string, string>; mem_limit?: number; memswap_limit?: number }
>;
};
const gateway = config.services["openclaw-gateway"]!.environment!;
expect(gateway[heapKey]).toBe(heap || "8192");
const gateway = config.services["openclaw-gateway"]!;
expect(gateway.environment?.[heapKey]).toBe(heap || "8192");
expect(Number(gateway.mem_limit)).toBe(limitGiB * 1024 ** 3);
expect(gateway.memswap_limit).toBe(gateway.mem_limit);
for (const [name, service] of Object.entries(config.services)) {
if (name !== "openclaw-gateway") {
expect(service.environment?.[heapKey], name).toBeUndefined();
expect(service.mem_limit, name).toBeUndefined();
expect(service.memswap_limit, name).toBeUndefined();
}
}
const launched = runLauncher(gateway[heapKey]);
const launched = runLauncher(gateway.environment?.[heapKey]);
expect(launched.status, launched.stderr).toBe(0);
const probe = JSON.parse(launched.stdout) as GatewayProbe;
expect(probe.options).toBe(`--max-old-space-size=${heap || "8192"}`);
Expand Down