Agent Skills › serithemage/serverless-openclaw › troubleshoot

troubleshoot

GitHub

排查CDK部署、Docker构建、Lambda代理及测试失败等常见问题，提供具体错误原因与解决方案。

.claude/skills/troubleshoot/SKILL.md serithemage/serverless-openclaw

触发场景

遇到开发或部署错误 CDK合成失败 Docker构建报错

安装

npx skills add serithemage/serverless-openclaw --skill troubleshoot -g -y

更多选项

非标准路径

npx skills add https://github.com/serithemage/serverless-openclaw/tree/main/.claude/skills/troubleshoot -g -y

不安装直接使用

npx skills use serithemage/serverless-openclaw@troubleshoot

指定 Agent (Claude Code)

npx skills add serithemage/serverless-openclaw --skill troubleshoot -a claude-code -g -y

安装 repo 全部 skill

npx skills add serithemage/serverless-openclaw --all -g -y

预览 repo 内 skill

npx skills add serithemage/serverless-openclaw --list

SKILL.md

Frontmatter

{
    "name": "troubleshoot",
    "description": "Troubleshoots common issues. Covers CDK deploy failures, Docker build errors, Lambda agent issues, test failures, and OpenClaw compatibility. Use when encountering errors during development or deployment.",
    "allowed-tools": "Read, Bash, Glob, Grep",
    "argument-hint": "[error description]"
}

Troubleshooting

Problem to investigate: $ARGUMENTS

Full references:

docs/deployment.md §10 — Deployment troubleshooting
docs/lambda-migration-journey.md — Deployment Obstacles section

Common Issues & Solutions

CDK / Synth

Problem	Cause	Solution
`Cannot find asset` during `cdk synth`	`packages/web/dist/` missing	Run `cd packages/web && npx vite build` first
`CDK Bootstrap version mismatch`	Outdated bootstrap	Run `cdk bootstrap`
`ROLLBACK_FAILED` on SecretsStack	AwsCustomResource partial failure	`aws cloudformation delete-stack --stack-name SecretsStack --deletion-mode FORCE_DELETE_STACK`, then redeploy
`ECR repository already exists`	CDK trying to create existing repo	Use `--force` delete or `Repository.fromRepositoryName()`
Cross-stack export removal error	Stack import in use	Use `--exclusively` flag + SSM decoupling pattern

Docker Build

Problem	Cause	Solution
TS error with `openclaw` dynamic import	Static analysis of dynamic path	Use variable path: `const mod = await import(/* @vite-ignore */ path)`
`OCI manifest` push error	Default buildx provenance	Add `--provenance=false` flag to `docker buildx build`
`npm ci` fails (husky postinstall)	prepare script runs in container	`npm pkg delete scripts.prepare && npm ci`

Lambda Agent

Problem	Cause	Solution
`Cannot find package`	Package installed globally, not in LAMBDA_TASK_ROOT	Install in `$LAMBDA_TASK_ROOT`, not `/usr/local`
`exports map` resolution failure	Node ESM named exports	Use `file://` URL import: `import(\`file://${path}`)`
Bedrock discovery timeout (56s)	Auto-discovery scans all regions	Set `bedrockDiscovery.enabled: false` in OpenClaw config
`extensionAPI not found`	Not in exports map	Use `file://` URL: `import(\`file://${ocRoot}/dist/extensionAPI.js`)`

OpenClaw Compatibility

Problem	Cause	Solution
v2026.2.14 breaks: scope error	Default-deny scope system, device pairing required	Pin to v2026.2.13 (fastest compatible)
`operator.write` stripped	Missing device pairing in v2026.2.14+	Use v2026.2.13 or implement device pairing
`device` field validation fails	Empty publicKey/signature strings	Omit `device` field entirely (it's Optional)
`client.mode: "operator"` invalid	Not a valid Literal type	Use `"backend"` or `"node"`

Tests

Problem	Cause	Solution
`vi.mock` variable not in scope	Hoisting moves mock above variable declaration	Use `vi.hoisted()` for variables referenced in mocks
E2E tests run with unit tests	Default vitest include matches all `.test.ts`	Exclude `*/.e2e.test.ts` in `vitest.config.ts`
`workspace:*` not resolved	pnpm syntax used in npm workspace	Use `"*"` for workspace dependencies

AWS / IAM

Problem	Cause	Solution
`launchType` + `capacityProviderStrategy` conflict	Cannot specify both in RunTask	Remove `launchType`, use `capacityProviderStrategy` only
Lambda env var `{{resolve:ssm-secure:...}}` fails	Not supported for Lambda env vars	Pass SSM path as env var, resolve at runtime via `resolveSecrets()`
ECS Task new secret inaccessible	Execution role not updated	Add `ssm:GetParameters` to execution role policy
Empty env vars from `.env`	`export $(cat .env	xargs)` silently sets empty