OpenClaw Feishu Reasoning UX

Improve OpenClaw's Feishu reply experience by customizing streaming cards, raw reasoning visibility, card 2.0 layouts, collapsible panels, titles, colors, and fallback send paths. Use this whenever a user wants a better Feishu reply UX for OpenClaw, especially when raw reasoning disappeared, only Thinking shows, titles/styles regressed, cards feel too black-box, or the user wants Feishu replies to become more observable, layered, and customizable.

# OpenClaw Feishu Reasoning UX

Use this skill when the task is specifically about how OpenClaw messages appear inside Feishu.

This skill is for:
- card 2.0 styling
- streaming card behavior
- raw reasoning visibility
- collapsible reasoning panels
- title/template/color behavior
- fallback send paths
- regressions after restart, update, or session rollover

This skill is not for generic Feishu app setup, permissions, or bot connectivity unless those directly block card delivery.

## Read this first

Before making any change, read:

- [references/proven-case-and-pitfalls.md](./references/proven-case-and-pitfalls.md)

Do not skip it.

That document contains:
- the real successful practice this skill came from
- the real failure patterns we actually hit
- the specific traps that repeatedly caused false fixes or broken environments

Only after reading it should you decide whether the current case is:
- close enough to a proven pattern to continue
- only safe for low-risk card changes
- or outside the proven cases and should be explained to the user first

## Core operating principles

This is not a "silently fix everything" skill.

Treat it as:
- a diagnosis-first skill
- a user-consent-first customization skill
- a backup-and-rollback-first skill

The user keeps control of the risky steps.

That means:
- if the current environment differs from the proven cases, do not silently push ahead
- explain the difference, the likely risk, the expected benefit, and the rollback path first
- let the user decide whether to continue

When in doubt:
- prefer stopping with a clear explanation
- prefer low-risk card-layer improvements
- avoid self-authorized runtime/session/provider surgery

## Real-world reference case

This skill was validated on a specific real deployment shape, but do not treat every detail of that environment as a hard prerequisite.

Proven reference case:
- a specific OpenClaw build/runtime path
- OpenClaw's built-in Feishu channel
- `minimax-cn/MiniMax-M2.7`
- not `minimax-portal/*`

Use this case as a comparison point, not as a rigid gate.

The details that matter most are usually:
- whether the channel is the built-in OpenClaw Feishu channel
- whether the current path emits usable live reasoning signals
- whether the installed build still exposes the runtime hooks this customization depends on
- provider/model path
- loaded runtime path (`src/` vs `dist/`)
- session/service state

Treat OpenClaw version/build as a compatibility factor, not a rigid gate by itself.
The question is not "is the version identical to the reference case?"
The question is "does this installed build still expose compatible runtime contracts?"

Do not overfocus on WSL vs non-WSL unless logs show environment differences are actually relevant.

## Interaction style for end users

Assume many users do not know Feishu card internals, provider runtime details, or OpenClaw file layout.

So when using this skill:
- explain findings in plain language first
- translate technical diagnosis into user-facing choices
- proactively offer the next reasonable options instead of stopping at analysis
- ask short, concrete preference questions when appearance or behavior depends on taste

Good examples:
- `我检测到当前模型不支持可见 raw reasoning，但我们还能把回复卡片做成 2.0 风格、带颜色标题和折叠面板。你想先改这个吗？`
- `我检测到现在标题已经能改。你想让标题显示什么文案？直接告诉我文字就行。`
- `当前模型只能流正式回答，不能流 raw 思考。我可以帮你切到支持的模型，或者保留当前模型只优化卡片样式。你想走哪条？`

Do not dump only low-level findings if the user clearly wants a working outcome.

## What success looks like

A correct Feishu customization usually has to satisfy all of these:
- Feishu messages still send reliably
- normal answer streaming still works
- raw reasoning, if enabled, shows in the intended form
- final answer still closes correctly
- new sessions do not silently lose the behavior
- changes are documented so they can be rebuilt later

Do not optimize appearance first if delivery or runtime lane selection is broken.

## Safe rollout strategy

Default to phased customization, not all-at-once modification.

The safest order is:

1. **Low-risk card appearance changes**
- titles
- colors
- card 2.0 layout
- collapsible containers
- rich text / container structure

2. **Normal answer streaming behavior**
- confirm ordinary streaming still works
- keep reasoning disabled for now if needed

3. **Raw reasoning capability check**
- verify whether the current model/provider/runtime truly supports readable live reasoning

4. **Raw reasoning runtime/session wiring**
- only after capability is proven
- only after ordinary card sending and answer streaming are stable

5. **Persistence fixes**
- only after the behavior is correct
- patch new-session defaults or shared runtime logic so it survives restart and `/new`

If the user only wants a better Feishu card experience, stop after phase 1 or phase 2.
Do not pull them into high-risk reasoning/runtime changes unnecessarily.

### How to explain phased rollout to the user

Prefer language like:

- `我们先做风险最小的部分：标题、颜色和卡片 2.0 容器。`
- `普通回复流式先确认稳定，再决定要不要动 raw reasoning。`
- `raw reasoning 这层要先看模型支不支持，支持再继续。`

Do not jump straight into runtime surgery unless the user clearly wants visible raw reasoning.

## Backup and rollback are mandatory

Before any non-trivial Feishu customization, create a recovery trail first.

This is not optional.

Always do all three before risky changes:

1. **Create a written change note**
- summarize what is about to be changed
- record the current model/provider/session assumptions
- record the target files

2. **Create a file backup**
- back up every file that will be modified
- use a clearly named backup directory with date/time context
- do this before the first edit, not after

3. **Prepare a user-facing rollback guide**
- tell the user exactly how to restore the prior state
- include file paths
- include whether a gateway restart is needed after restore

If the user environment is fragile, prefer incremental backup points instead of one large backup.

### Minimum rollback instructions to provide

Before claiming a risky change is ready to test, the agent must be able to tell the user:

- which files were changed
- where the backups were saved
- how to restore the backups
- whether restoring requires a gateway restart
- how to verify that rollback succeeded

If you cannot explain rollback clearly, the change is not ready.

## Necessary conditions vs compatibility factors

Separate hard requirements from things that only increase risk.
Do not treat every difference from the reference case as a blocker.

### Necessary conditions for raw reasoning customization

These are the conditions that actually have to be true before you try to modify the raw reasoning lane:

1. The current Feishu path is truly the intended channel implementation.
- Verify whether the user is on:
  - OpenClaw's built-in Feishu channel
  - or Feishu's own official plugin / another integration path
- Do not treat those as interchangeable.

2. The current session is truly running on the intended provider/model path.
- Verify the active session transcript, not just the global default.
- Do not trust the agent saying it already switched.

3. The current runtime path is actually producing usable reasoning signals.
- Check `~/.openclaw/logs/raw-stream.jsonl`.
- For MiniMax CN, look for `assistant_thinking_stream`.
- If the current request produces no usable reasoning signal, card changes cannot create true raw reasoning.

4. The installed OpenClaw build still exposes compatible runtime hooks.
- Examples:
  - `reasoningMode = "stream"` is honored
  - `onReasoningStream` / `onReasoningEnd` can reach the final `replyOptions`
  - the dispatcher contract still matches the patch strategy
- A different version is acceptable if these contracts are still compatible.

5. A rollback path is ready before risky edits.
- If you cannot explain backup and rollback clearly, do not patch runtime/session/provider layers.

### Compatibility factors that can change the implementation

These are impor