feat(cli): read agent messages from files

ooiuuii · ooiuuii · commit cd05d4a0224e · 2026-06-21T17:00:07.000+08:00
diff --git a/docs/cli/agent.md b/docs/cli/agent.md
@@ -23,7 +23,8 @@ Related:
 
 ## Options
 
-- `-m, --message <text>`: required message body
+- `-m, --message <text>`: message body
+- `--message-file <path>`: read the message body from a UTF-8 file
 - `-t, --to <dest>`: recipient used to derive the session key
 - `--session-key <key>`: explicit session key to use for routing
 - `--session-id <id>`: explicit session id
@@ -45,6 +46,7 @@ Related:
 ```bash
 openclaw agent --to +15555550123 --message "status update" --deliver
 openclaw agent --agent ops --message "Summarize logs"
+openclaw agent --agent ops --message-file ./task.md
 openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
 openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"
 openclaw agent --agent ops --session-key incident-42 --message "Summarize status"
@@ -56,6 +58,7 @@ openclaw agent --agent ops --message "Run locally" --local
 
 ## Notes
 
+- Pass exactly one of `--message` or `--message-file`. `--message-file` preserves multiline file content after removing an optional UTF-8 BOM, and rejects files that are not valid UTF-8.
 - Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front.
 - `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
 - `--local` and embedded fallback runs are treated as one-shot runs. Bundled MCP loopback resources and warm Claude stdio sessions opened for that local process are retired after the reply, so scripted invocations do not keep local child processes alive.
diff --git a/docs/tools/agent-send.md b/docs/tools/agent-send.md
@@ -22,6 +22,15 @@ programmatic delivery.
 
   </Step>
 
+  <Step title="Send a multiline prompt from a file">
+    ```bash
+    openclaw agent --agent ops --message-file ./task.md
+    ```
+
+    This reads a valid UTF-8 file as the agent message body.
+
+  </Step>
+
   <Step title="Target a specific agent or session">
     ```bash
     # Target a specific agent
@@ -56,7 +65,8 @@ programmatic delivery.
 
 | Flag                          | Description                                                 |
 | ----------------------------- | ----------------------------------------------------------- |
-| `--message \<text\>`          | Message to send (required)                                  |
+| `--message \<text\>`          | Inline message to send                                      |
+| `--message-file \<path\>`     | Read the message from a valid UTF-8 file                    |
 | `--to \<dest\>`               | Derive session key from a target (phone, chat id)           |
 | `--session-key \<key\>`       | Use an explicit session key                                 |
 | `--agent \<id\>`              | Target a configured agent (uses its `main` session)         |
@@ -76,6 +86,8 @@ programmatic delivery.
 
 - By default, the CLI goes **through the Gateway**. Add `--local` to force the
   embedded runtime on the current machine.
+- Pass exactly one of `--message` or `--message-file`. File messages preserve
+  multiline content after removing an optional UTF-8 BOM.
 - If the Gateway is unreachable, the CLI **falls back** to the local embedded run.
 - Session selection: `--to` derives the session key (group/channel targets
   preserve isolation; direct chats collapse to `main`).
@@ -102,6 +114,9 @@ openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
 # Turn with thinking level
 openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
 
+# Multiline prompt from a file
+openclaw agent --agent ops --message-file ./task.md
+
 # Exact session key
 openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"
 
diff --git a/src/cli/program/register.agent-turn.ts b/src/cli/program/register.agent-turn.ts
@@ -34,7 +34,8 @@ export function registerAgentTurnCommand(
   program
     .command("agent")
     .description("Run an agent turn via the Gateway (use --local for embedded)")
-    .requiredOption("-m, --message <text>", "Message body for the agent")
+    .option("-m, --message <text>", "Message body for the agent")
+    .option("--message-file <path>", "Read the agent message body from a UTF-8 file")
     .option("-t, --to <number>", "Recipient number in E.164 used to derive the session key")
     .option("--session-key <key>", "Explicit session key (agent:<id>:<key>, or scoped to --agent)")
     .option("--session-id <id>", "Use an explicit session id")
@@ -71,6 +72,7 @@ ${theme.heading("Examples:")}
 ${formatHelpExamples([
   ['openclaw agent --to +15555550123 --message "status update"', "Start a new session."],
   ['openclaw agent --agent ops --message "Summarize logs"', "Use a specific agent."],
+  ["openclaw agent --agent ops --message-file ./task.md", "Read a multiline message file."],
   [
     'openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"',
     "Target an exact session key.",
diff --git a/src/cli/program/register.agent.test.ts b/src/cli/program/register.agent.test.ts
@@ -118,6 +118,17 @@ describe("agent command registration", () => {
     expect(deps).toBeUndefined();
   });
 
+  it("forwards a message file to the agent command", async () => {
+    await runCli(["agent", "--message-file", "task.md", "--agent", "ops"]);
+
+    const [options, callRuntime, deps] = commandCall(agentCliCommandMock);
+    expect((options as { message?: string }).message).toBeUndefined();
+    expect((options as { messageFile?: string }).messageFile).toBe("task.md");
+    expect((options as { agent?: string }).agent).toBe("ops");
+    expect(callRuntime).toBe(runtime);
+    expect(deps).toBeUndefined();
+  });
+
   it("accepts a model override for one-shot agent runs", async () => {
     await runCli(["agent", "--message", "hi", "--agent", "ops", "--model", "openai/gpt-5.4"]);
 
diff --git a/src/commands/agent-via-gateway.test.ts b/src/commands/agent-via-gateway.test.ts
@@ -308,6 +308,55 @@ describe("agentCliCommand", () => {
     });
   });
 
+  it("reads a UTF-8 message file for gateway dispatch", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "task.md");
+      const messageBody = 'first line\n```json\n{"ok":true}\n```\nsecond line\n';
+      fs.writeFileSync(messageFile, `\uFEFF${messageBody}`, "utf8");
+      mockGatewaySuccessReply();
+
+      await agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime);
+
+      expect(callGateway).toHaveBeenCalledTimes(1);
+      const request = requireRecord(requireFirstCallArg(callGateway, "gateway"), "gateway request");
+      const params = requireRecord(request.params, "gateway request params");
+      expect(params.message).toBe(messageBody);
+    });
+  });
+
+  it("rejects inline and file messages together", async () => {
+    await expect(
+      agentCliCommand(
+        { message: "inline", messageFile: "task.md", sessionKey: "agent:main:incident-42" },
+        runtime,
+      ),
+    ).rejects.toThrow("Use either --message or --message-file, not both");
+    expect(callGateway).not.toHaveBeenCalled();
+  });
+
+  it("reports missing message files before dispatch", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "missing.md");
+
+      await expect(
+        agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime),
+      ).rejects.toThrow("Message file not found");
+      expect(callGateway).not.toHaveBeenCalled();
+    });
+  });
+
+  it("rejects message files that are not valid UTF-8", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "task.bin");
+      fs.writeFileSync(messageFile, Buffer.from([0xff]));
+
+      await expect(
+        agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime),
+      ).rejects.toThrow("Message file must be valid UTF-8");
+      expect(callGateway).not.toHaveBeenCalled();
+    });
+  });
+
   it.each(["/new", "/RESET", "/reset check status"] as const)(
     "uses backend admin authority for %s gateway commands",
     async (message) => {
@@ -1817,6 +1866,26 @@ describe("agentCliCommand", () => {
     });
   }
 
+  it("rejects /compact from --message-file before any gateway or embedded turn", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "compact.md");
+      fs.writeFileSync(messageFile, "/compact:Keep recent decisions.", "utf8");
+      callGateway.mockRejectedValue(createGatewayTimeoutError());
+
+      await agentCliCommand(
+        { messageFile, sessionId: "locked-session", runId: "locked-run", timeout: "0" },
+        runtime,
+      );
+    });
+
+    expect(callGateway).not.toHaveBeenCalled();
+    expect(agentCommand).not.toHaveBeenCalled();
+    expect(runtime.exit).toHaveBeenCalledWith(1);
+    const errorMessages = mockMessages(runtime.error);
+    expect(errorMessages.some((m) => m.includes("openclaw sessions compact"))).toBe(true);
+    expect(errorMessages.some((m) => m.includes("EMBEDDED FALLBACK"))).toBe(false);
+  });
+
   it("does not mistake a /compacting-prefixed message for the /compact control command", async () => {
     await withTempStore(async () => {
       mockGatewaySuccessReply();
diff --git a/src/commands/agent-via-gateway.ts b/src/commands/agent-via-gateway.ts
@@ -1,5 +1,7 @@
 // Gateway-first agent CLI implementation with embedded fallback for local/runtime failures.
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { TextDecoder } from "node:util";
 import { resolveTimerTimeoutMs } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
@@ -64,7 +66,8 @@ const GATEWAY_TIMEOUT_FALLBACK_SESSION_PREFIX = "gateway-fallback-";
 const GATEWAY_TRANSIENT_CONNECT_RETRY_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 15_000] as const;
 
 type AgentCliOpts = {
-  message: string;
+  message?: string;
+  messageFile?: string;
   agent?: string;
   model?: string;
   to?: string;
@@ -85,6 +88,9 @@ type AgentCliOpts = {
   extraSystemPrompt?: string;
   local?: boolean;
 };
+type AgentDispatchOpts = Omit<AgentCliOpts, "messageFile"> & {
+  message: string;
+};
 
 type AgentCliSignal = "SIGINT" | "SIGTERM";
 type AgentCliProcessLike = {
@@ -110,6 +116,7 @@ const AGENT_CLI_SIGNAL_EXIT_CODES: Record<AgentCliSignal, number> = {
   SIGINT: 130,
   SIGTERM: 143,
 };
+const MESSAGE_FILE_DECODER = new TextDecoder("utf-8", { fatal: true });
 
 let embeddedAgentCommandPromise: Promise<EmbeddedAgentCommandModule["agentCommand"]> | undefined;
 let agentSessionModulePromise: Promise<AgentSessionModule> | undefined;
@@ -172,6 +179,63 @@ function protectJsonStdout(opts: Pick<AgentCliOpts, "json">): void {
   }
 }
 
+function missingAgentMessageError(): Error {
+  return new Error(
+    `Missing message. Use ${formatCliCommand('openclaw agent --message "..." --agent <id>')} or ${formatCliCommand("openclaw agent --message-file <path> --agent <id>")}.`,
+  );
+}
+
+function formatMessageFileReadFailure(messageFile: string, err: unknown): string {
+  const code =
+    typeof (err as { code?: unknown })?.code === "string" ? (err as { code: string }).code : "";
+  if (code === "ENOENT") {
+    return `Message file not found: ${messageFile}`;
+  }
+  if (code === "EISDIR") {
+    return `Message file is a directory: ${messageFile}`;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return `Unable to read message file ${messageFile}: ${message}`;
+}
+
+async function readAgentMessageFile(messageFile: string): Promise<string> {
+  let buffer: Buffer;
+  try {
+    buffer = await readFile(messageFile);
+  } catch (err) {
+    throw new Error(formatMessageFileReadFailure(messageFile, err), { cause: err });
+  }
+  try {
+    return MESSAGE_FILE_DECODER.decode(buffer).replace(/^\uFEFF/, "");
+  } catch {
+    throw new Error(`Message file must be valid UTF-8: ${messageFile}`);
+  }
+}
+
+async function resolveAgentMessageOpts(opts: AgentCliOpts): Promise<AgentDispatchOpts> {
+  const { messageFile: rawMessageFile, ...rest } = opts;
+  const messageFile = rawMessageFile?.trim();
+  const hasInlineMessage = opts.message !== undefined;
+  if (hasInlineMessage && messageFile) {
+    throw new Error("Use either --message or --message-file, not both.");
+  }
+  if (rawMessageFile !== undefined && !messageFile) {
+    throw new Error("--message-file must not be empty.");
+  }
+  if (messageFile) {
+    const message = await readAgentMessageFile(messageFile);
+    if (!message.trim()) {
+      throw new Error(`Message file is empty: ${messageFile}`);
+    }
+    return { ...rest, message };
+  }
+  const message = (opts.message ?? "").trim();
+  if (!message) {
+    throw missingAgentMessageError();
+  }
+  return { ...rest, message };
+}
+
 function parseTimeoutSeconds(opts: { cfg: OpenClawConfig; timeout?: string }) {
   const raw =
     opts.timeout !== undefined
@@ -287,7 +351,9 @@ function validateExplicitSessionKeyForDispatch(
   }
 }
 
-async function normalizeSessionKeyOptsForDispatch(opts: AgentCliOpts): Promise<AgentCliOpts> {
+async function normalizeSessionKeyOptsForDispatch(
+  opts: AgentDispatchOpts,
+): Promise<AgentDispatchOpts> {
   const rawSessionKey = opts.sessionKey?.trim();
   const rawTo = opts.to?.trim();
   if (!rawSessionKey && !opts.sessionId?.trim() && classifySessionKeyShape(rawTo) === "agent") {
@@ -567,7 +633,7 @@ function createGatewayTimeoutFallbackSession(agentId?: string): {
 }
 
 async function resolveAgentIdForGatewayTimeoutFallback(
-  opts: AgentCliOpts,
+  opts: AgentDispatchOpts,
 ): Promise<string | undefined> {
   const explicitSessionKey = opts.sessionKey?.trim();
   if (classifySessionKeyShape(explicitSessionKey) === "agent") {
@@ -619,17 +685,15 @@ function formatInFlightGatewayAgentMessage(response: GatewayAgentResponse): stri
 }
 
 async function agentViaGatewayCommand(
-  opts: AgentCliOpts,
+  opts: AgentDispatchOpts,
   runtime: RuntimeEnv,
   signalBridge: ReturnType<typeof createAgentCliSignalBridge>,
 ) {
   protectJsonStdout(opts);
-  const body = (opts.message ?? "").trim();
+  const body = opts.message;
   const explicitSessionKey = opts.sessionKey?.trim();
-  if (!body) {
-    throw new Error(
-      `Missing message. Use ${formatCliCommand('openclaw agent --message "..." --agent <id>')} or pass --to/--session-key/--session-id for an existing conversation.`,
-    );
+  if (!body.trim()) {
+    throw missingAgentMessageError();
   }
   if (!opts.to && !opts.sessionId && !opts.agent && !explicitSessionKey) {
     throw new Error(
@@ -805,7 +869,7 @@ async function agentViaGatewayCommand(
 }
 
 async function agentViaGatewayCommandWithTransientRetries(
-  opts: AgentCliOpts,
+  opts: AgentDispatchOpts,
   runtime: RuntimeEnv,
   signalBridge: ReturnType<typeof createAgentCliSignalBridge>,
 ) {
@@ -838,18 +902,19 @@ export async function agentCliCommand(
   deps?: AgentCliDeps,
 ) {
   protectJsonStdout(opts);
+  const messageOpts = await resolveAgentMessageOpts(opts);
   // `/compact` cannot run as a plain CLI agent turn: the slash-command handler
   // rejects CLI-originated senders, so the message would fall through to a
   // normal turn and exit 0 without compacting anything (issue #90640 Gap B).
   // Fail loudly and point at the first-class command instead of no-opping.
-  if (isCompactControlCommand(opts.message)) {
+  if (isCompactControlCommand(messageOpts.message)) {
     runtime.error?.(
       "Slash commands cannot be executed via --message from the CLI. Use: openclaw sessions compact <key>",
     );
     runtime.exit(1);
     return undefined;
   }
-  const dispatchOpts = await normalizeSessionKeyOptsForDispatch(opts);
+  const dispatchOpts = await normalizeSessionKeyOptsForDispatch(messageOpts);
   validateExplicitSessionKeyForDispatch(dispatchOpts);
   const gatewayDispatchOpts = dispatchOpts.runId
     ? dispatchOpts
