Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/a2ui/data-and-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,12 +167,14 @@ an `agent.request` node event:
{
"message": "CANVAS_A2UI action=submit session=main surface=main component=btn-1 host=… instance=… ctx=… default=update_canvas",
"sessionKey": "main",
"thinking": "low",
"deliver": false,
"key": "<action-id>"
}
```

The event carries no `thinking` override, so a canvas action runs with the
session's own effort setting.

`AgentMessageFormatter` is a deliberate byte-for-byte port of the Android
node's formatter - the gateway parses tags identically across platforms.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -294,7 +294,7 @@ internal static string BuildPreset(
preset.Append("repeat-penalty = ").AppendLine(Invariant(sampling.RepetitionPenalty));
preset.Append("presence-penalty = ").AppendLine(Invariant(sampling.PresencePenalty));
preset.AppendLine("jinja = true");
preset.AppendLine("reasoning = on");
// Keep llama-server at its default auto mode so each request can turn reasoning off.
preset.AppendLine("reasoning-format = deepseek");
preset.AppendLine("context-shift = true");
return preset.ToString();
Expand Down
110 changes: 101 additions & 9 deletions src/OpenClaw.Connection/LocalAi/LocalAiGatewayProviderDefinition.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
// bool matches = LocalAiGatewayProviderDefinition.MatchesProviderJson(cliOutputJson, install);
using OpenClaw.Shared.Inference.Catalog;
using System.Text.Json;
using System.Text.Json.Nodes;

namespace OpenClaw.Connection.LocalAi;

Expand All @@ -25,6 +26,13 @@ public static class LocalAiGatewayProviderDefinition
public const int ProviderTimeoutSeconds = 300;
public const int MaximumOutputTokens = 8_192;

/// <summary>
/// Model keys the effort metadata needs. A protocol-4 Gateway can predate
/// them (thinkingLevelMap arrived in 2026.6.5) and rejects them as unknown.
/// </summary>
public static readonly IReadOnlyList<string> EffortMetadataKeys =
["thinkingLevelMap", "supportedReasoningEfforts", "reasoningEffortMap"];

/// <summary>Caps generated Gateway output tokens to one quarter of the selected context window.</summary>
public static int GetMaximumOutputTokens(int contextTokens) =>
Math.Min(MaximumOutputTokens, contextTokens / 4);
Expand All @@ -41,20 +49,53 @@ public static string BuildProviderJson(LocalAiResolvedInstall install)
/// so the API key may be either its written value or the documented
/// redaction marker; every routing and model field must still match.
/// </summary>
public static bool MatchesProviderJson(string providerJson, LocalAiResolvedInstall install, string? apiKey = null)
public static bool MatchesProviderJson(string providerJson, LocalAiResolvedInstall install, string? apiKey = null) =>
MatchesProviderJson(providerJson, install, apiKey, legacy: false);

/// <summary>Recognizes an exact current or pre-effort-metadata managed provider for ownership recovery.</summary>
public static bool MatchesCurrentOrLegacyProviderJson(
string providerJson, LocalAiResolvedInstall install, string? apiKey = null) =>
MatchesProviderJson(providerJson, install, apiKey) ||
MatchesLegacyProviderJson(providerJson, install, apiKey);

/// <summary>Rebuilds a trusted provider for rollback in the exact observed managed shape.</summary>
public static string BuildProviderJsonForRollback(string priorProviderJson, LocalAiResolvedInstall install)
{
if (MatchesProviderJson(priorProviderJson, install))
return BuildProviderJson(install);
if (MatchesLegacyProviderJson(priorProviderJson, install))
return BuildLegacyProviderJson(install);
throw new InvalidDataException("The original Local AI provider is not an exact managed configuration.");
}

/// <summary>Checks that recovery restored the same managed model-metadata shape.</summary>
public static bool MatchesSameManagedProviderShape(
string priorProviderJson, string restoredProviderJson, LocalAiResolvedInstall install)
{
if (MatchesProviderJson(priorProviderJson, install))
return MatchesProviderJson(restoredProviderJson, install);
return MatchesLegacyProviderJson(priorProviderJson, install) &&
MatchesLegacyProviderJson(restoredProviderJson, install);
}

/// <summary>Recognizes only the exact provider shape published before effort metadata was added.</summary>
public static bool MatchesLegacyProviderJson(string providerJson, LocalAiResolvedInstall install, string? apiKey = null) =>
MatchesProviderJson(providerJson, install, apiKey, legacy: true);

private static bool MatchesProviderJson(string providerJson, LocalAiResolvedInstall install, string? apiKey, bool legacy)
{
ArgumentException.ThrowIfNullOrWhiteSpace(providerJson);
ArgumentNullException.ThrowIfNull(install);

try
{
using JsonDocument actual = JsonDocument.Parse(providerJson);
using JsonDocument expected = JsonDocument.Parse(BuildProviderJson(install, apiKey ?? "llama-local"));
using JsonDocument expected = JsonDocument.Parse(BuildProviderJson(install, apiKey ?? "llama-local", legacy));
if (JsonEquals(actual.RootElement, expected.RootElement))
return true;

using JsonDocument redacted = JsonDocument.Parse(
BuildProviderJson(install, CliRedactedApiKey));
BuildProviderJson(install, CliRedactedApiKey, legacy));
return JsonEquals(actual.RootElement, redacted.RootElement);
}
catch (JsonException)
Expand Down Expand Up @@ -101,13 +142,33 @@ private static bool JsonEquals(JsonElement left, JsonElement right)
}

/// <summary>Builds the managed provider JSON for a resolved install and explicit local API credential.</summary>
public static string BuildProviderJson(LocalAiResolvedInstall install, string apiKey)
public static string BuildProviderJson(LocalAiResolvedInstall install, string apiKey) =>
BuildProviderJson(install, apiKey, legacy: false);

/// <summary>
/// Builds the exact pre-effort provider for Gateways whose model schema
/// rejects effort metadata. Effort Off cannot disable reasoning there.
/// </summary>
public static string BuildLegacyProviderJson(LocalAiResolvedInstall install, string apiKey = "llama-local") =>
BuildProviderJson(install, apiKey, legacy: true);

private static string BuildProviderJson(LocalAiResolvedInstall install, string apiKey, bool legacy)
{
ArgumentNullException.ThrowIfNull(install);
_ = LocalAiApiCredentialStore.RequireApiKey(apiKey);
LocalModelInfo model = GetQualifiedModel(install);
Uri endpoint = install.Endpoint
?? throw new InvalidOperationException("The verified Local AI endpoint is required.");
string[]? efforts = legacy ? null : model.ReasoningProfile switch
{
LocalModelReasoningProfile.Qwen38 => ["none", "low", "medium", "high"],
LocalModelReasoningProfile.QwenOnOff => ["none", "medium"],
_ => null,
};
object? thinkingLevelMap = efforts is null ? null :
model.ReasoningProfile == LocalModelReasoningProfile.QwenOnOff
? new { minimal = (string?)null, high = (string?)null }
: new { minimal = (string?)null };

var value = new
{
Expand All @@ -127,12 +188,40 @@ public static string BuildProviderJson(LocalAiResolvedInstall install, string ap
contextWindow = install.Manifest.ContextLength,
contextTokens = install.Manifest.ContextLength,
maxTokens = GetMaximumOutputTokens(install.Manifest.ContextLength),
compat = new { supportsTools = true, supportsUsageInStreaming = true },
compat = new
{
supportsTools = true,
supportsUsageInStreaming = true,
supportsReasoningEffort = efforts is null ? (bool?)null : true,
supportedReasoningEfforts = efforts,
reasoningEffortMap = efforts is null ? null : new { off = "none" },
},
thinkingLevelMap,
api = ApiType,
},
},
};
return JsonSerializer.Serialize(value);
JsonObject provider = (JsonObject)JsonSerializer.SerializeToNode(value)!;
if (efforts is null)
{
// Keep the old shape for templates whose reasoning vocabulary has
// not been verified. Null map entries on qualified templates are
// meaningful and must remain in the serialized configuration.
JsonObject configuredModel = (JsonObject)((JsonArray)provider["models"]!)[0]!;
JsonObject compat = (JsonObject)configuredModel["compat"]!;
compat.Remove("supportsReasoningEffort");
compat.Remove("supportedReasoningEfforts");
compat.Remove("reasoningEffortMap");
configuredModel.Remove("thinkingLevelMap");
}
return provider.ToJsonString();
}

/// <summary>Builds the exact model array for a guarded legacy-provider migration.</summary>
public static string BuildProviderModelsJson(LocalAiResolvedInstall install)
{
using JsonDocument provider = JsonDocument.Parse(BuildProviderJson(install));
return provider.RootElement.GetProperty("models").GetRawText();
}

/// <summary>Builds the Gateway primary-model identifier for a resolved managed install.</summary>
Expand Down Expand Up @@ -176,10 +265,13 @@ public static bool TryReadPrimaryModelJson(string json, out string? model)
}
}

/// <summary>Builds an atomic Gateway batch that writes both provider definition and primary model.</summary>
public static string BuildProviderBatchJson(LocalAiResolvedInstall install)
/// <summary>
/// Builds an atomic Gateway batch that writes both provider definition and
/// primary model, in the pre-effort shape when <paramref name="legacy"/> is set.
/// </summary>
public static string BuildProviderBatchJson(LocalAiResolvedInstall install, bool legacy = false)
{
using JsonDocument provider = JsonDocument.Parse(BuildProviderJson(install));
using JsonDocument provider = JsonDocument.Parse(BuildProviderJson(install, "llama-local", legacy));
return JsonSerializer.Serialize(new[]
{
new { path = ProviderPath, value = (object)provider.RootElement.Clone() },
Expand Down
59 changes: 42 additions & 17 deletions src/OpenClaw.SetupEngine/LocalAiGatewayConfiguration.cs
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,16 @@ internal static class LocalAiGatewayConfigBuilder
internal const string ProviderPath = LocalAiGatewayProviderDefinition.ProviderPath;
internal const string PrimaryModelPath = LocalAiGatewayProviderDefinition.PrimaryModelPath;

public static string BuildBatchJson(SetupContext context)
public static string BuildBatchJson(SetupContext context, bool legacy = false)
{
ArgumentNullException.ThrowIfNull(context);
var install = context.LocalAiResolvedInstall
?? throw new InvalidOperationException("The Local AI install receipt is required.");
_ = context.LocalAiEligibility?.Plan
?? throw new InvalidOperationException("The qualified Local AI plan is required.");
using JsonDocument provider = JsonDocument.Parse(
LocalAiGatewayProviderDefinition.BuildProviderJson(install));
using JsonDocument provider = JsonDocument.Parse(legacy
? LocalAiGatewayProviderDefinition.BuildLegacyProviderJson(install)
: LocalAiGatewayProviderDefinition.BuildProviderJson(install));
object[] operations =
[
new { path = ProviderPath, value = (object)provider.RootElement.Clone() },
Expand Down Expand Up @@ -59,8 +60,11 @@ public static string BuildRecoveryRestoreBatchJson(
{
ArgumentNullException.ThrowIfNull(prior);
ArgumentNullException.ThrowIfNull(originalInstall);
// Recreate the exact pre-recovery model shape with the known local
// credential; never replay a CLI-redacted API key from the snapshot.
using JsonDocument provider = JsonDocument.Parse(
LocalAiGatewayProviderDefinition.BuildProviderJson(originalInstall));
LocalAiGatewayProviderDefinition.BuildProviderJsonForRollback(
prior.ProviderJson!, originalInstall));
using JsonDocument primary = JsonDocument.Parse(prior.PrimaryModelJson!);
object[] operations =
[
Expand Down Expand Up @@ -118,15 +122,15 @@ public override async Task<StepResult> ExecuteAsync(SetupContext ctx, Cancellati
if (prior.ProviderExisted)
{
bool matchesCurrentInstall = install.Endpoint is not null &&
LocalAiGatewayProviderDefinition.MatchesProviderJson(prior.ProviderJson!, install);
LocalAiGatewayProviderDefinition.MatchesCurrentOrLegacyProviderJson(prior.ProviderJson!, install);
bool matchesRecoveryInstall = false;
if (!matchesCurrentInstall &&
ctx.LocalAiRecoveryOriginalInstall is { Endpoint: not null } originalInstall)
{
string originalPrimary = JsonSerializer.Serialize(
LocalAiGatewayProviderDefinition.BuildPrimaryModel(originalInstall));
matchesRecoveryInstall =
LocalAiGatewayProviderDefinition.MatchesProviderJson(
LocalAiGatewayProviderDefinition.MatchesCurrentOrLegacyProviderJson(
prior.ProviderJson!,
originalInstall) &&
JsonEquals(originalPrimary, expectedPrimary);
Expand Down Expand Up @@ -201,6 +205,17 @@ public override async Task<StepResult> ExecuteAsync(SetupContext ctx, Cancellati

string batchJson = LocalAiGatewayConfigBuilder.BuildBatchJson(ctx);
CommandResult result = await ApplyBatchAsync(ctx, batchJson, "LOCAL_AI_GATEWAY_CONFIGURED", ct);
if (result.ExitCode != 0 && !result.TimedOut &&
await RejectsBatchAsync(ctx, batchJson, ct).ConfigureAwait(false))
{
// Effort metadata needs Gateway 2026.6.5 or later; protocol-4 Gateways
// before it reject the model keys. The dry-run wrote nothing, so publish
// the exact pre-effort provider instead of failing setup.
ctx.Logger.Warn("The Gateway does not accept Local AI effort metadata (it needs OpenClaw Gateway 2026.6.5 or later). " +
"Publishing the earlier provider shape, so Effort Off cannot turn reasoning off on this Gateway.");
result = await ApplyBatchAsync(
ctx, LocalAiGatewayConfigBuilder.BuildBatchJson(ctx, legacy: true), "LOCAL_AI_GATEWAY_CONFIGURED", ct);
}
if (result.ExitCode != 0 || result.TimedOut ||
!result.Stdout.Contains("LOCAL_AI_GATEWAY_CONFIGURED", StringComparison.Ordinal))
{
Expand Down Expand Up @@ -254,9 +269,8 @@ public override async Task RollbackAsync(SetupContext ctx, CancellationToken ct)
if (recoveryOriginal is not null &&
current.ProviderExisted == prior.ProviderExisted &&
(!current.ProviderExisted ||
LocalAiGatewayProviderDefinition.MatchesProviderJson(
current.ProviderJson!,
recoveryOriginal)) &&
LocalAiGatewayProviderDefinition.MatchesSameManagedProviderShape(
prior.ProviderJson!, current.ProviderJson!, recoveryOriginal)) &&
current.PrimaryModelExisted == prior.PrimaryModelExisted &&
(!current.PrimaryModelExisted ||
JsonEquals(current.PrimaryModelJson!, prior.PrimaryModelJson!)))
Expand All @@ -266,8 +280,9 @@ public override async Task RollbackAsync(SetupContext ctx, CancellationToken ct)
}

string expectedPrimary = JsonSerializer.Serialize(LocalAiGatewayConfigBuilder.ExpectedPrimaryModel(ctx));
// Setup writes the pre-effort shape to Gateways that reject effort metadata.
if (!current.ProviderExisted || !current.PrimaryModelExisted ||
!LocalAiGatewayProviderDefinition.MatchesProviderJson(
!LocalAiGatewayProviderDefinition.MatchesCurrentOrLegacyProviderJson(
current.ProviderJson!,
ctx.LocalAiResolvedInstall!) ||
!JsonEquals(current.PrimaryModelJson!, expectedPrimary))
Expand Down Expand Up @@ -367,9 +382,8 @@ private static async Task ReconcileFailedRecoveryRestoreAsync(
bool originalRestored =
observed.ProviderExisted == prior.ProviderExisted &&
(!observed.ProviderExisted ||
LocalAiGatewayProviderDefinition.MatchesProviderJson(
observed.ProviderJson!,
recoveryOriginal)) &&
LocalAiGatewayProviderDefinition.MatchesSameManagedProviderShape(
prior.ProviderJson!, observed.ProviderJson!, recoveryOriginal)) &&
observed.PrimaryModelExisted == prior.PrimaryModelExisted &&
(!observed.PrimaryModelExisted ||
JsonEquals(observed.PrimaryModelJson!, prior.PrimaryModelJson!));
Expand All @@ -383,7 +397,7 @@ private static async Task ReconcileFailedRecoveryRestoreAsync(
observed.ProviderExisted &&
observed.PrimaryModelExisted &&
ctx.LocalAiResolvedInstall is { } replacement &&
LocalAiGatewayProviderDefinition.MatchesProviderJson(
LocalAiGatewayProviderDefinition.MatchesCurrentOrLegacyProviderJson(
observed.ProviderJson!,
replacement) &&
JsonEquals(
Expand Down Expand Up @@ -444,7 +458,7 @@ fallbackModel is not null &&
}

if ((current.ProviderExisted &&
!LocalAiGatewayProviderDefinition.MatchesProviderJson(current.ProviderJson!, install)) ||
!LocalAiGatewayProviderDefinition.MatchesCurrentOrLegacyProviderJson(current.ProviderJson!, install)) ||
(current.PrimaryModelExisted &&
!currentPrimaryIsManaged &&
!currentPrimaryIsFallback &&
Expand Down Expand Up @@ -537,24 +551,35 @@ private static Task<CommandResult> CaptureStateAsync(SetupContext ctx, Cancellat
user: ctx.Config.Wsl.User, inputViaStdin: true);
}

/// <summary>True only when a dry-run of the batch completed and the Gateway rejected it.</summary>
private static async Task<bool> RejectsBatchAsync(SetupContext ctx, string batchJson, CancellationToken ct)
{
CommandResult validated = await ApplyBatchAsync(
ctx, batchJson, "LOCAL_AI_GATEWAY_VALIDATED", ct, apply: false).ConfigureAwait(false);
return validated.ExitCode != 0 && !validated.TimedOut;
}

private static Task<CommandResult> ApplyBatchAsync(
SetupContext ctx,
string batchJson,
string successMarker,
CancellationToken ct)
CancellationToken ct,
bool apply = true)
{
var environment = new Dictionary<string, string>
{
[BatchVariable] = Convert.ToBase64String(Encoding.UTF8.GetBytes(batchJson)),
};
// A validation-only run stops after the dry-run (":" is the shell no-op).
string write = apply ? "openclaw config set --batch-file \"$batch_file\"" : ":";
string script = $$"""
set -e
{{ctx.WslPathPrefix}}
batch_file="$(mktemp)"
trap 'rm -f "$batch_file"' EXIT
printf '%s' "$OPENCLAW_LOCAL_AI_BATCH_B64" | base64 -d > "$batch_file"
openclaw config set --batch-file "$batch_file" --dry-run
openclaw config set --batch-file "$batch_file"
{{write}}
echo {{successMarker}}
""";
return ctx.Commands.RunInWslAsync(
Expand Down
Loading