- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`

- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`

- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`

- `channels.webchat.textChunkLimit` → `gateway.webchat.chatHistoryMaxChars`; other retired `channels.webchat` fields are removed

- `routing.queue` → `messages.queue`

- `routing.bindings` → top-level `bindings`

- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`

WebChat options:

- `gateway.webchat.chatHistoryMaxChars`: maximum character count for text fields in `chat.history` responses. When a transcript entry exceeds this limit, Gateway truncates long text fields and may replace oversized messages with a placeholder. Per-request `maxChars` can also be sent by the client to override this default for a single `chat.history` call.

- `gateway.webchat.chatHistoryMaxChars`: maximum character count for text fields in `chat.history` responses. When a transcript entry exceeds this limit, Gateway truncates long text fields and may replace oversized messages with a placeholder. The bundled Control UI uses this Gateway default; API clients can still send per-request `maxChars` to override it for a single `chat.history` call. Legacy `channels.webchat` config is retired; run `openclaw doctor --fix` to remove it.

Related global options:

expected: 4000,

},

{

name: "honors webchat textChunkLimit override from config",

name: "ignores retired webchat textChunkLimit channel config",

cfg: {

channels: {

webchat: { textChunkLimit: 16000 },

provider: "webchat" as const,

accountId: undefined,

options: undefined,

expected: 16000,

expected: 4000,

},

{

name: "falls back to default when webchat has no override",

cfg: { channels: { webchat: { chunkMode: "newline" as const } } },

provider: "webchat",

accountId: undefined,

expected: "newline",

expected: "length",

},

] as const)(

"resolves default/provider/account/internal chunk mode for $provider $accountId",

import { resolveAccountEntry } from "../routing/account-lookup.js";

import { normalizeAccountId } from "../routing/session-key.js";

import { chunkTextByBreakResolver } from "../shared/text-chunking.js";

import { INTERNAL_MESSAGE_CHANNEL } from "../utils/message-channel-constants.js";

export type TextChunkProvider = ChannelId;

? opts.fallbackLimit

: DEFAULT_CHUNK_LIMIT;

const providerOverride = (() => {

if (!provider) {

if (!provider || provider === INTERNAL_MESSAGE_CHANNEL) {

return undefined;

}

const channelsConfig = cfg?.channels as Record<string, unknown> | undefined;

provider?: TextChunkProvider,

accountId?: string | null,

): ChunkMode {

if (!provider) {

if (!provider || provider === INTERNAL_MESSAGE_CHANNEL) {

return DEFAULT_CHUNK_MODE;

}

const channelsConfig = cfg?.channels as Record<string, unknown> | undefined;

docsPath: "/channels/channel-routing",

tests: ["src/commands/doctor/shared/channel-legacy-config-migrate.test.ts"],

}),

deprecatedCompatRecord({

code: "doctor-webchat-channel-config",

status: "removed",

owner: "channel",

introduced: "2026-05-18",

deprecated: "2026-05-31",

warningStarts: "2026-05-31",

removeAfter: "2026-08-31",

source: "channels.webchat",

migration: "src/commands/doctor/shared/legacy-config-migrations.channels.ts",

replacement: "gateway.webchat.chatHistoryMaxChars for WebChat history limits",

docsPath: "/web/webchat",

tests: ["src/commands/doctor/shared/legacy-config-migrate.test.ts"],

notes:

"WebChat is an internal control surface, not a configurable outbound channel. Runtime ignores the retired channel key; doctor preserves the history-size intent when possible.",

}),

deprecatedCompatRecord({

code: "doctor-tts-provider-aliases",

owner: "tts",

});

});

describe("legacy WebChat channel config migrate", () => {

it("moves WebChat textChunkLimit to the gateway history cap and removes channels.webchat", () => {

const raw = {

channels: {

webchat: {

textChunkLimit: 16000,

chunkMode: "newline",

},

discord: {

textChunkLimit: 2000,

},

},

};

expect(findLegacyConfigIssues(raw).map((issue) => issue.path)).toEqual(["channels.webchat"]);

const res = migrateLegacyConfigForTest(raw);

expect(res.config?.gateway?.webchat?.chatHistoryMaxChars).toBe(16000);

expect(res.config?.channels).toEqual({

discord: {

textChunkLimit: 2000,

},

});

expect(res.changes).toStrictEqual([

"Moved channels.webchat.textChunkLimit → gateway.webchat.chatHistoryMaxChars.",

"Removed retired channels.webchat config.",

]);

});

it("removes channels.webchat without overwriting an existing gateway history cap", () => {

const res = migrateLegacyConfigForTest({

gateway: {

webchat: {

chatHistoryMaxChars: 8000,

},

},

channels: {

webchat: {

textChunkLimit: 16000,

},

},

});

expect(res.config?.gateway?.webchat?.chatHistoryMaxChars).toBe(8000);

expect(res.config).not.toHaveProperty("channels");

expect(res.changes).toStrictEqual(["Removed retired channels.webchat config."]);

});

it("drops invalid WebChat textChunkLimit values instead of creating invalid gateway config", () => {

const res = migrateLegacyConfigForTest({

channels: {

webchat: {

textChunkLimit: 600000,

},

},

});

expect(res.config).not.toHaveProperty("gateway");

expect(res.config).not.toHaveProperty("channels");

expect(res.changes).toStrictEqual([

"Removed channels.webchat.textChunkLimit (not a valid gateway.webchat.chatHistoryMaxChars value).",

"Removed retired channels.webchat config.",

]);

});

});

describe("legacy thread binding spawn migrate", () => {

it("moves matching split spawn flags to unified spawnSessions", () => {

const res = migrateLegacyConfigForTest({

},

];

const WEBCHAT_CHANNEL_RULES: LegacyConfigRule[] = [

{

path: ["channels", "webchat"],

message:

'channels.webchat is retired; use gateway.webchat.chatHistoryMaxChars for WebChat history limits. Run "openclaw doctor --fix".',

},

];

const WEBCHAT_CHAT_HISTORY_MAX_CHARS_LIMIT = 500_000;

function migrateRetiredWebchatChannelConfig(raw: Record<string, unknown>, changes: string[]): void {

const channels = getRecord(raw.channels);

if (!channels || !hasOwnKey(channels, "webchat")) {

return;

}

const webchat = getRecord(channels.webchat);

const legacyTextChunkLimit = webchat?.textChunkLimit;

const gateway = getRecord(raw.gateway) ?? {};

const gatewayWebchat = getRecord(gateway.webchat) ?? {};

const canMoveLegacyTextChunkLimit =

Number.isInteger(legacyTextChunkLimit) &&

legacyTextChunkLimit > 0 &&

legacyTextChunkLimit <= WEBCHAT_CHAT_HISTORY_MAX_CHARS_LIMIT;

if (canMoveLegacyTextChunkLimit && gatewayWebchat.chatHistoryMaxChars === undefined) {

gatewayWebchat.chatHistoryMaxChars = legacyTextChunkLimit;

gateway.webchat = gatewayWebchat;

raw.gateway = gateway;

changes.push("Moved channels.webchat.textChunkLimit → gateway.webchat.chatHistoryMaxChars.");

} else if (

legacyTextChunkLimit !== undefined &&

gatewayWebchat.chatHistoryMaxChars === undefined

) {

changes.push(

"Removed channels.webchat.textChunkLimit (not a valid gateway.webchat.chatHistoryMaxChars value).",

);

}

delete channels.webchat;

raw.channels = channels;

cleanupEmptyRecord(raw, "channels");

changes.push("Removed retired channels.webchat config.");

}

export const LEGACY_CONFIG_MIGRATIONS_CHANNELS: LegacyConfigMigrationSpec[] = [

defineLegacyConfigMigration({

id: "channels.webchat->gateway.webchat",

describe: "Remove retired WebChat channel config",

legacyRules: WEBCHAT_CHANNEL_RULES,

apply: (raw, changes) => {

migrateRetiredWebchatChannelConfig(raw, changes);

},

}),

defineLegacyConfigMigration({

id: "legacy-group-routing->channel-groups",

describe:

expect(request).toHaveBeenCalledWith("chat.history", {

sessionKey: "main",

limit: 100,

maxChars: 4000,

});

expect(request).not.toHaveBeenCalledWith("models.list", { view: "configured" });

const sessionsListPayload = findRequestPayload(

sessionKey: "global",

agentId: "work",

limit: 100,

maxChars: 4000,

});

const sessionsListPayload = findRequestPayload(

request as unknown as MockCallSource,

sessionKey: "agent:work:main",

agentId: "work",

limit: 100,

maxChars: 4000,

});

const sessionsListPayload = findRequestPayload(

request as unknown as MockCallSource,

sessionKey: "global",

agentId: "ops",

limit: 100,

maxChars: 4000,

});

const sessionsListPayload = findRequestPayload(

request as unknown as MockCallSource,

expect(request).toHaveBeenCalledWith("chat.history", {

sessionKey: "unknown",

limit: 100,

maxChars: 4000,

});

const sessionsListPayload = findRequestPayload(

request as unknown as MockCallSource,

sessionKey: "global",

agentId: "work",

limit: 100,

maxChars: 4000,

});

expect(host.chatMessages).toStrictEqual([]);

});

expect(request).toHaveBeenCalledWith("chat.history", {

sessionKey: "main",

limit: 100,

maxChars: 4000,

});

expect(state.chatMessages).toEqual([

{ role: "assistant", content: [{ type: "text", text: "visible answer" }] },

const SYNTHETIC_TRANSCRIPT_REPAIR_RESULT =

"[openclaw] missing tool result in session history; inserted synthetic error result for transcript repair.";

const CHAT_HISTORY_REQUEST_LIMIT = 100;

const CHAT_HISTORY_REQUEST_MAX_CHARS = 4_000;

const STARTUP_CHAT_HISTORY_RETRY_TIMEOUT_MS = 60_000;

const STARTUP_CHAT_HISTORY_DEFAULT_RETRY_MS = 500;

const STARTUP_CHAT_HISTORY_MAX_RETRY_MS = 5_000;

sessionKey,

...(requestAgentId ? { agentId: requestAgentId } : {}),

limit: CHAT_HISTORY_REQUEST_LIMIT,

maxChars: CHAT_HISTORY_REQUEST_MAX_CHARS,

});

break;

} catch (err) {