diff --git a/extensions/acpx/index.ts b/extensions/acpx/index.ts
index 1042613eadd3..70159088ac2b 100644
--- a/extensions/acpx/index.ts
+++ b/extensions/acpx/index.ts
@@ -1,3 +1,7 @@
+/**
+ * ACPX runtime plugin entry. It registers the embedded ACP backend service and
+ * wires reply-dispatch hooks into the plugin SDK runtime.
+ */
 import { tryDispatchAcpReplyHook } from "openclaw/plugin-sdk/acp-runtime-backend";
 import { createAcpxRuntimeService } from "./register.runtime.js";
 import type { OpenClawPluginApi } from "./runtime-api.js";
diff --git a/extensions/acpx/register.runtime.ts b/extensions/acpx/register.runtime.ts
index 9710d6d320e6..85958b3cb0cd 100644
--- a/extensions/acpx/register.runtime.ts
+++ b/extensions/acpx/register.runtime.ts
@@ -1,3 +1,7 @@
+/**
+ * Lazy ACPX runtime service registration. The plugin exposes an ACP backend
+ * immediately, then imports the heavier service only when a session needs it.
+ */
 import {
   getAcpRuntimeBackend,
   registerAcpRuntimeBackend,
@@ -62,6 +66,7 @@ function createDeferredRuntime(state: DeferredServiceState): AcpRuntime {
   return createLazyAcpRuntimeProxy(resolveRuntime);
 }
 
+/** Creates the plugin service that registers ACPX as an ACP runtime backend. */
 export function createAcpxRuntimeService(
   params: CreateAcpxRuntimeServiceParams = {},
 ): OpenClawPluginService {
diff --git a/extensions/acpx/runtime-api.ts b/extensions/acpx/runtime-api.ts
index 468158bb5671..7fcbad0b947a 100644
--- a/extensions/acpx/runtime-api.ts
+++ b/extensions/acpx/runtime-api.ts
@@ -1,3 +1,7 @@
+/**
+ * Public runtime API barrel for ACPX. Core and plugin consumers import these
+ * SDK-facing ACP runtime contracts instead of reaching into ACPX internals.
+ */
 export type { AcpRuntimeErrorCode } from "openclaw/plugin-sdk/acp-runtime-backend";
 export {
   AcpRuntimeError,
diff --git a/extensions/acpx/setup-api.ts b/extensions/acpx/setup-api.ts
index 6c8899314de0..7c843971f845 100644
--- a/extensions/acpx/setup-api.ts
+++ b/extensions/acpx/setup-api.ts
@@ -1,3 +1,7 @@
+/**
+ * ACPX setup plugin entry. It auto-enables setup when ACP config already points
+ * at the embedded ACPX runtime backend.
+ */
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 
diff --git a/extensions/acpx/src/command-line.ts b/extensions/acpx/src/command-line.ts
index 2684fa7acb3f..5008bb18066e 100644
--- a/extensions/acpx/src/command-line.ts
+++ b/extensions/acpx/src/command-line.ts
@@ -1,7 +1,13 @@
+/**
+ * Small shell-command helpers for ACPX-launched processes. Splitting supports
+ * simple quoted command strings from config without invoking a shell parser.
+ */
+/** Quote one command argument for display or config serialization. */
 export function quoteCommandPart(value: string): string {
   return JSON.stringify(value);
 }
 
+/** Split a command string into argv-like parts using simple quote/backslash rules. */
 export function splitCommandParts(value: string): string[] {
   const parts: string[] = [];
   let current = "";
diff --git a/extensions/acpx/src/config-schema.ts b/extensions/acpx/src/config-schema.ts
index 71f38cf1db5e..5c0aa398caee 100644
--- a/extensions/acpx/src/config-schema.ts
+++ b/extensions/acpx/src/config-schema.ts
@@ -1,19 +1,28 @@
+/**
+ * ACPX plugin configuration schema and public config types. Runtime setup uses
+ * this file as the single source of truth for validation and defaulting.
+ */
 import { z } from "zod";
 
 const ACPX_PERMISSION_MODES = ["approve-all", "approve-reads", "deny-all"] as const;
+/** Permission policy applied to interactive ACPX tool requests. */
 export type AcpxPermissionMode = (typeof ACPX_PERMISSION_MODES)[number];
 
 const ACPX_NON_INTERACTIVE_POLICIES = ["deny", "fail"] as const;
+/** Permission policy applied when ACPX cannot ask a human for approval. */
 export type AcpxNonInteractivePermissionPolicy = (typeof ACPX_NON_INTERACTIVE_POLICIES)[number];
 
+/** Default session timeout for ACPX runtime turns. */
 export const DEFAULT_ACPX_TIMEOUT_SECONDS = 120;
 
+/** Raw MCP server command config accepted from plugin configuration. */
 export type McpServerConfig = {
   command: string;
   args?: string[];
   env?: Record<string, string>;
 };
 
+/** Normalized MCP server config emitted to the ACPX runtime process. */
 export type AcpxMcpServer = {
   name: string;
   command: string;
@@ -21,6 +30,7 @@ export type AcpxMcpServer = {
   env: Array<{ name: string; value: string }>;
 };
 
+/** User-provided ACPX plugin configuration before defaults are resolved. */
 export type AcpxPluginConfig = {
   cwd?: string;
   stateDir?: string;
@@ -36,6 +46,7 @@ export type AcpxPluginConfig = {
   agents?: Record<string, { command: string; args?: string[] }>;
 };
 
+/** Fully resolved ACPX config consumed by the runtime service. */
 export type ResolvedAcpxPluginConfig = {
   cwd: string;
   stateDir: string;
@@ -76,6 +87,7 @@ const McpServerConfigSchema = z.object({
     .describe("Environment variables for the MCP server"),
 });
 
+/** Zod schema for validating raw ACPX plugin config from OpenClaw config. */
 export const AcpxPluginConfigSchema = z.strictObject({
   cwd: nonEmptyTrimmedString("cwd must be a non-empty string").optional(),
   stateDir: nonEmptyTrimmedString("stateDir must be a non-empty string").optional(),