Implementation:Openclaw Openclaw MsgContext Envelope

Knowledge Sources	OpenClaw
Domains	Agent_Runtime, Messaging
Last Updated	2026-02-06 12:00 GMT

Overview

Concrete type definition for the unified inbound message envelope provided by the OpenClaw agent runtime.

Description

MsgContext is the canonical TypeScript type that every channel adapter populates when an inbound message arrives. It is a flat record of optional fields covering message body variants, sender identity, media attachments, group/thread context, forwarding metadata, reply-to references, provider surface hints, and originating channel information for reply routing. The type is defined in src/auto-reply/templating.ts at lines 13-132.

A companion type, FinalizedMsgContext, is produced by finalizeInboundContext(). It narrows the CommandAuthorized field from optional to a required boolean (default-deny: false), ensuring that downstream consumers cannot accidentally treat an unauthorized message as authorized.

The envelope is consumed throughout the agent runtime: by the routing layer to resolve agent sessions, by command parsing to detect and authorize commands, by the reply pipeline to assemble prompts and deliver responses, and by media understanding to attach transcriptions and descriptions to the context.

Usage

Import MsgContext when building a channel adapter or any component that processes inbound messages. Import FinalizedMsgContext when writing code that runs after finalization and requires the authorization guarantee.

Code Reference

Source Location

• Repository: openclaw
• File: src/auto-reply/templating.ts
• Lines: 13-132 (MsgContext), 134-140 (FinalizedMsgContext)

Signature

export type MsgContext = {
  Body?: string;
  BodyForAgent?: string;
  RawBody?: string;
  CommandBody?: string;
  BodyForCommands?: string;
  CommandArgs?: CommandArgs;
  From?: string;
  To?: string;
  SessionKey?: string;
  AccountId?: string;
  ParentSessionKey?: string;
  MessageSid?: string;
  MessageSidFull?: string;
  MessageSids?: string[];
  MessageSidFirst?: string;
  MessageSidLast?: string;
  ReplyToId?: string;
  ReplyToIdFull?: string;
  ReplyToBody?: string;
  ReplyToSender?: string;
  ReplyToIsQuote?: boolean;
  ForwardedFrom?: string;
  ForwardedFromType?: string;
  ForwardedFromId?: string;
  ForwardedFromUsername?: string;
  ForwardedFromTitle?: string;
  ForwardedFromSignature?: string;
  ForwardedFromChatType?: string;
  ForwardedFromMessageId?: number;
  ForwardedDate?: number;
  ThreadStarterBody?: string;
  ThreadLabel?: string;
  MediaPath?: string;
  MediaUrl?: string;
  MediaType?: string;
  MediaDir?: string;
  MediaPaths?: string[];
  MediaUrls?: string[];
  MediaTypes?: string[];
  Sticker?: StickerMetadata;
  OutputDir?: string;
  OutputBase?: string;
  MediaRemoteHost?: string;
  Transcript?: string;
  MediaUnderstanding?: MediaUnderstandingOutput[];
  MediaUnderstandingDecisions?: MediaUnderstandingDecision[];
  LinkUnderstanding?: string[];
  Prompt?: string;
  MaxChars?: number;
  ChatType?: string;
  ConversationLabel?: string;
  GroupSubject?: string;
  GroupChannel?: string;
  GroupSpace?: string;
  GroupMembers?: string;
  GroupSystemPrompt?: string;
  UntrustedContext?: string[];
  OwnerAllowFrom?: Array<string | number>;
  SenderName?: string;
  SenderId?: string;
  SenderUsername?: string;
  SenderTag?: string;
  SenderE164?: string;
  Timestamp?: number;
  Provider?: string;
  Surface?: string;
  WasMentioned?: boolean;
  CommandAuthorized?: boolean;
  CommandSource?: "text" | "native";
  CommandTargetSessionKey?: string;
  GatewayClientScopes?: string[];
  MessageThreadId?: string | number;
  IsForum?: boolean;
  OriginatingChannel?: OriginatingChannelType;
  OriginatingTo?: string;
  HookMessages?: string[];
};

Import

import type { MsgContext, FinalizedMsgContext } from "../auto-reply/templating.js";

I/O Contract

Inputs

MsgContext is a type definition, not a function. It is populated by channel adapters. Key field groups:

Field Group	Representative Fields	Description
Message Body	Body, BodyForAgent, RawBody, CommandBody, BodyForCommands	Multiple representations of the message text for different consumers (prompt assembly, command detection, display).
Sender Identity	From, SenderName, SenderId, SenderUsername, SenderTag, SenderE164	Normalized identity of the message sender across channels.
Session Routing	SessionKey, AccountId, ParentSessionKey, To	Keys used to resolve which agent session handles this message.
Media	MediaPath, MediaUrl, MediaType, MediaPaths, MediaUrls, MediaTypes, Sticker	Attachments, stickers, and multi-media batches.
Reply/Forward	ReplyToId, ReplyToBody, ForwardedFrom, ForwardedFromId	Metadata about quoted replies and forwarded messages.
Group/Thread	ChatType, GroupSubject, GroupChannel, MessageThreadId, IsForum	Context about group conversations, threads, and forum topics.
Originating Channel	OriginatingChannel, OriginatingTo, Provider, Surface	Identifies which channel and destination the reply should route back to.
Authorization	CommandAuthorized, CommandSource, GatewayClientScopes, OwnerAllowFrom	Security-related fields controlling command execution permissions.

Outputs

Name	Type	Description
FinalizedMsgContext	Omit<MsgContext, "CommandAuthorized"> & { CommandAuthorized: boolean }	Produced by finalizeInboundContext(); guarantees CommandAuthorized is a concrete boolean (default false).

Usage Examples

Basic Usage

import type { MsgContext } from "../auto-reply/templating.js";

// Channel adapter populates the envelope
const ctx: MsgContext = {
  Body: "Hello, what is the weather today?",
  BodyForAgent: "Hello, what is the weather today?",
  From: "+15551234567",
  SessionKey: "agent:default:whatsapp:dm:15551234567",
  Provider: "whatsapp",
  SenderName: "Alice",
  SenderId: "15551234567",
  OriginatingChannel: "whatsapp",
  OriginatingTo: "15551234567",
  Timestamp: Date.now(),
};

// Pass to the reply pipeline
const reply = await getReplyFromConfig(ctx);

Related Pages

Implements Principle

• Principle:Openclaw_Openclaw_Message_Ingestion