openclaw - 💡(How to fix) Fix Feature Request: assistantPrefix on agentTurn payload (and agent defaults) to guarantee reply starts with fixed text

Summary

Add an optional assistantPrefix (or equivalent) string field to CronAgentTurnPayloadFields and to the agent-defaults config, so operators can force the assistant's reply to start with a specific string. This closes the door on preamble/narration at the protocol level, independently of how well-aligned the chosen (or fallback) model is.

Motivation

When a model in the fallback chain tends to narrate its reasoning inside content (rather than in a separate reasoning_content/thinking channel), it can leak multi-message preamble to downstream channels — even when the system prompt explicitly forbids narration.

Real incident (reproduced in production, 2026-04-20 21:02, UTC-3):

• A cron (agentTurn payload, WhatsApp delivery) was configured to invoke a skill that produces a fixed-template reminder starting with 🌙 Aplicações da NOITE — ….
• Primary model (openai-codex/gpt-5.3-codex) failed auth; chain fell through oc/gemma4:31b-cloud (rate limit) and oc/gemma4:26b (404) before succeeding on zai/glm-5.1.
• zai/glm-5.1 returned a response where the first paragraphs were planning narration ("Let me check if there's a peptide-reminder skill…", "Now let me check the most recent application files…", "The reminder should be sent to the WhatsApp group …"). The streaming pipeline published each paragraph as a separate WhatsApp message, followed by the correct reminder.
• Result: 4 messages posted to the group where 1 was expected.

Prompt hardening (the usual fix) handles 80–90% of cases but is not guaranteed — especially under fallback to less-aligned models. A protocol-level mitigation is needed for high-reliability automations like medical/medication reminders.

Proposal

Add an optional field:

// plugin-sdk/src/cron/types.d.ts
type CronAgentTurnPayloadFields = {
  message: string;
  model?: string;
  fallbacks?: string[];
  thinking?: string;
  timeoutSeconds?: number;
  allowUnsafeExternalContent?: boolean;
  externalContentSource?: HookExternalContentSource;
  lightContext?: boolean;
  toolsAllow?: string[];
  // NEW:
  assistantPrefix?: string;
};

And expose it symmetrically on agent defaults / agent-level config so ad-hoc agent invocations benefit too.

Provider semantics

When assistantPrefix is set, the gateway prepends it to the assistant turn using provider-native mechanisms:

• Anthropic — append an {role: "assistant", content: <prefix>} message at the end of messages[] (already supported by the API; the assistant continues from there).
• OpenAI-compatible (incl. zai, deepseek, openai, most Ollama cloud models) — the dominant convention today is to append an assistant message with the prefix; some providers additionally accept prefix: true (DeepSeek-style) to signal "continue, do not rewrite". Choose the variant the provider adapter supports; fall back to the simple assistant-message append.
• Ollama (oc / local) — use raw: true mode and append the prefix after the formatted system+user prompt, stopping normal chat formatting.
• Unsupported providers — silently no-op (log at debug), don't break the run.

CLI surface

openclaw cron edit <id> --assistant-prefix "🌙 Aplicações da NOITE — "
openclaw cron add   …    --assistant-prefix "…"

Example config (agent defaults)

{
  agents: {
    defaults: {
      model: "openai-codex/gpt-5.3-codex",
      fallbacks: ["zai/glm-5.1", "oc/gemma4:31b-cloud"],
      // NEW:
      assistantPrefix: null,  // per-cron override typical
    },
  },
}

Why not just prompt harder?

That's the current workaround and it helps — we've done it in our skill's SKILL.md. But:

1. Fallback models vary wildly in alignment. A prompt firm enough for gpt-5.3-codex may not be enough for glm-5.1 or qwen-max-thinking. You can either bloat the skill prompt with provider-specific escape hatches, or fix it once at the protocol level.
2. It's an extra hop. Every skill author has to re-discover the discipline independently. assistantPrefix centralizes the guarantee.
3. Fixed templates are a common pattern for cron-delivered messages (reminders, digests, summaries). When there's a known first line, leaning on prompt obedience is weaker than just … starting with that line.

Alternatives considered

• Post-filter regex in the channel adapter — fragile; drops content mid-stream; no reliable heuristic for "this line is narration vs. actual content".
• Forbid reasoning-style models on fallback chains — limits operator flexibility; reasoning models are otherwise great.
• Separate reasoning_content cleanly in the provider adapter — orthogonal and also worth doing (tracked separately), but only helps when the model emits reasoning on a distinct channel; doesn't help when narration comes in content directly (as glm-5.1 did).

Acceptance sketch

• Schema updated (CronAgentTurnPayloadFields, agent-defaults, relevant Zod/JSON-schema validators).
• At least 2 provider adapters honor the prefix (Anthropic + one OpenAI-compatible). Others are fine no-oping until support is added.
• CLI flag --assistant-prefix on cron add/edit and agent run.
• Doc page at docs.openclaw.ai/gateway/configuration under agents / cron payload.
• Test: cron with assistantPrefix: "X" forces the first characters of delivered content to be X, across configured providers.

Impact

Low-risk additive change. No existing config needs to move; absent the field, behavior is identical to today.

Happy to submit a PR if the direction is agreed on — would need pointers on where the provider adapters live for non-Anthropic providers and whether the preference is for a single adapter entry point or per-provider branches.