diff --git a/.gitignore b/.gitignore
index 9b618a3..8265703 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,5 @@ plugin/**/*.js
 plugin/**/*.js.map
 plugin/**/*.d.ts
 plugin/**/*.d.ts.map
+# Hand-written ambient declarations are tracked; only compiled .d.ts above is ignored.
+!plugin/openclaw-sdk.d.ts
diff --git a/plugin/openclaw-sdk.d.ts b/plugin/openclaw-sdk.d.ts
new file mode 100644
index 0000000..d71146c
--- /dev/null
+++ b/plugin/openclaw-sdk.d.ts
@@ -0,0 +1,25 @@
+// Ambient declarations for the focused subpaths of the openclaw plugin SDK
+// that this plugin needs at compile time.
+//
+// We intentionally do NOT take a `dependencies` (or `devDependencies`) entry
+// on the openclaw npm package itself: openclaw is provided by the host
+// gateway at runtime, and listing it as a file:/.../openclaw devDep breaks
+// the installer's `npm install --omit=dev` step because npm/arborist trips
+// over openclaw's own (deeply nested) dependency graph.
+//
+// These declarations cover only what we use here. They are deliberately
+// permissive — the runtime contract is whatever the gateway hands us, and
+// we guard each api access with optional chaining or a fallback at call site.
+
+declare module 'openclaw/plugin-sdk/plugin-entry' {
+  export function definePluginEntry<T extends {
+    id: string;
+    name: string;
+    description?: string;
+    register: (api: any) => void | Promise<void>;
+  }>(opts: T): T;
+}
+
+declare module 'openclaw/plugin-sdk/core' {
+  export type OpenClawPluginApi = unknown;
+}