Bug type

Behavior bug (incorrect output/state without crash)

Summary

After correctly and explicitly configuring the tools.media.image model in openclaw.json, when a model that does not support image understanding is activated in a channel, the openclaw gateway will not automatically call the configured image understanding model to convert the image into a prompt and inject it into the prompt of the activated model that does not support image understanding.

Steps to reproduce

1.WIN10, compile version 26.3.13 of OPENCLAW from GTIHUB source code.
2.Enter onboard mode for the first time, skipping all options that can be skipped. Do not configure the model's API KEY.
3.After that, the OPENCLAW dashboard can open normally, and openclaw doctor shows no related error messages.

Expected behavior

1. ...openclaw doctor shows no related error messages...At this time, the OPENCLAW_AGENT_DIR variable exist in the Windows 10 environment variables.
2. After correctly configuring the activation model and image understanding model in openclaw.json, the image understanding model should be automatically invoked when the activation model does not support image input.

Actual behavior

1. ...openclaw doctor shows no related error messages...At this time, the OPENCLAW_AGENT_DIR variable does not exist in the Windows 10 environment variables.
   2.After correctly configuring the activation model and image understanding model in openclaw.json, when the activation model does not support image input, the image understanding model is not automatically invoked. This results in images being correctly interpreted only when the current channel's activation model is manually switched to a model that supports image understanding in the DASHBOARD.

OpenClaw version

v2026.3.13

Operating system

Windows 10

Install method

git clone https://github.com/openclaw/openclaw.git

Model

minimax m2.7

Provider / routing chain

feishu->openclaw gateway->agent channel->minimax api(api key)

Additional provider/model setup details

No response

Logs, screenshots, and evidence

1. Bug at the code level: The agentDirparameter is missing in dispatch-acp.ts

File: src/auto-reply/reply/dispatch-acp.ts

Line Numbers: Approximately 273-278

Problematic Code:
if (!params.ctx.MediaUnderstanding?.length) {
try {
await applyMediaUnderstanding({
ctx: params.ctx,
cfg: params.cfg,
// ← The `agentDir` parameter is missing here!
});
Signature of the applyMediaUnderstandingfunction:
export async function applyMediaUnderstanding(params: {
ctx: MsgContext;
cfg: OpenClawConfig;
agentDir?: string; // ← Optional parameter
providers?: Record<string, MediaUnderstandingProvider>;
activeModel?: ActiveMediaModel;
}): Promise<ApplyMediaUnderstandingResult>
2. The Role of agentDir

agentDiris used for:

Locating the models.jsonfile (ensureOpenClawModelsJson)

Loading the authentication storage (discoverAuthStorage)

Finding the model registry (discoverModels)

When agentDiris missing, describeImageWithModelwill fallback to resolveOpenClawAgentDir(). This function:

First reads the environment variables OPENCLAW_AGENT_DIRor PI_CODING_AGENT_DIR

Otherwise, uses the default path ~/.openclaw/agents/main/agent

Theoretically, if configured correctly, this fallback path should also work. However, actual testing indicates that the pipeline still fails silently.

Impact and severity

Severity:very annoying

Additional information

Interim Fix (Verified Effective)

Date: 2026-03-26 16:00 GMT+8

Verification Result: ✅ Success

Solution: Set the environment variable OPENCLAW_AGENT_DIR

Set the system environment variable OPENCLAW_AGENT_DIRto point to the agent working directory, bypassing the bug in dispatch-acp.tswhere the agentDirparameter is missing.
Test-Path "C:\Users\USER.openclaw\agents\main\agent"
Permanently Effective (Windows)

"This PC" → Properties → Advanced system settings → Environment Variables → System variables → New

Variable name: OPENCLAW_AGENT_DIR

Variable value: C:\Users\USER.openclaw\agents\main\agent

Click OK, then restart the gateway.
Interim Fix (Verified Effective)

Date: 2026-03-26 16:00 GMT+8

Verification Result: ✅ Success

Solution: Set the environment variable OPENCLAW_AGENT_DIR

Set the system environment variable OPENCLAW_AGENT_DIRto point to the agent working directory, bypassing the bug in dispatch-acp.tswhere the agentDirparameter is missing.

Steps

1. Confirm Directory Exists

复制
Test-Path "C:\Users\USER.openclaw\agents\main\agent"

If it returns True, the directory exists, and you can proceed. If it returns False, the directory does not exist (gateway has never created an agent session), and this solution is temporarily not applicable.

2. Set Environment Variable (PowerShell)

复制

Effective for the current session only (invalid after restart)

$env:OPENCLAW_AGENT_DIR = "C:\Users\USER.openclaw\agents\main\agent"
openclaw gateway restart

3. Permanently Effective (Windows)

"This PC" → Properties → Advanced system settings → Environment Variables → System variables → New

Variable name: OPENCLAW_AGENT_DIR

Variable value: C:\Users\USER.openclaw\agents\main\agent

Click OK, then restart the gateway.

Verification

Send an image to a Feishu channel configured with MiniMax-M2.7 and observe if the reply correctly includes a textual description of the image content.

Principle

Internally, applyMediaUnderstandingcalls describeImageWithModel, which in turn calls ensureOpenClawModelsJson. When the agentDirparameter is missing, it falls back to resolveOpenClawAgentDir(). This function checks the OPENCLAW_AGENT_DIRenvironment variable. After setting it, the pipeline can correctly locate models.jsonand authentication information, allowing image understanding to execute.

Permanent Fix (Requires Source Code Modification)
File to Modify

src/auto-reply/reply/dispatch-acp.ts

Modification Location

Approximately lines 273-278, at the call site of applyMediaUnderstanding.

Modification Content
// Before modification
await applyMediaUnderstanding({
ctx: params.ctx,
cfg: params.cfg,
// Missing agentDir
});

// After modification
await applyMediaUnderstanding({
ctx: params.ctx,
cfg: params.cfg,
agentDir: resolveOpenClawAgentDir(), // Add this line
});
You also need to import resolveOpenClawAgentDir.
cd W:\OPENCLAW\openclaw
pnpm build
pnpm link --global
openclaw gateway restart