Skip to content
Merged
Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
2b7bbe8
feat(inference): add a non-interactive reasoning-effort input for com…
laitingsheng Jul 28, 2026
0df0c88
Merge remote-tracking branch 'origin/main' into feat/reasoning-effort…
laitingsheng Jul 28, 2026
4817d69
fix(inference): scope the reasoning-effort mutation to the provider t…
laitingsheng Jul 28, 2026
a5df976
docs(inference): correct the accepted reasoning-effort values and whe…
laitingsheng Jul 28, 2026
999b756
fix(inference): clear the session reasoning effort for a non-recordin…
laitingsheng Jul 28, 2026
1bd1f20
merge(main): sync reasoning-effort work with current main
apurvvkumaria Jul 28, 2026
2fdf58e
fix(inference): enforce reasoning effort boundaries
apurvvkumaria Jul 28, 2026
8adb82f
docs(inference): clarify reasoning effort scope
apurvvkumaria Jul 28, 2026
166054a
test(inference): type reasoning effort fixture
apurvvkumaria Jul 28, 2026
62cfeee
test(inference): keep reasoning effort fixtures linear
apurvvkumaria Jul 28, 2026
2f0c04d
fix(inference): expose effective reasoning effort
apurvvkumaria Jul 28, 2026
b47d473
merge(main): sync reasoning-effort diagnostics
apurvvkumaria Jul 28, 2026
f680df0
refactor(inference): preserve architecture budgets
apurvvkumaria Jul 28, 2026
230953d
fix(inference): validate reasoning effort route
apurvvkumaria Jul 28, 2026
2810852
merge(main): sync reasoning effort validation
apurvvkumaria Jul 28, 2026
ef92cb6
fix(inference): preserve runtime reasoning effort
apurvvkumaria Jul 28, 2026
b75d244
merge(main): sync reasoning effort runtime validation
apurvvkumaria Jul 28, 2026
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
2 changes: 2 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -1022,6 +1022,7 @@ ARG NEMOCLAW_INFERENCE_API=openai-completions
ARG NEMOCLAW_CONTEXT_WINDOW=131072
ARG NEMOCLAW_MAX_TOKENS=4096
ARG NEMOCLAW_REASONING=false
ARG NEMOCLAW_REASONING_EFFORT=
ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
# Comma-separated list of input modalities accepted by the primary model
# (e.g. "text" or "text,image" for vision-capable models). OpenClaw's
Expand Down Expand Up @@ -1101,6 +1102,7 @@ ENV NEMOCLAW_MODEL=${NEMOCLAW_MODEL} \
NEMOCLAW_CONTEXT_WINDOW=${NEMOCLAW_CONTEXT_WINDOW} \
NEMOCLAW_MAX_TOKENS=${NEMOCLAW_MAX_TOKENS} \
NEMOCLAW_REASONING=${NEMOCLAW_REASONING} \
NEMOCLAW_REASONING_EFFORT=${NEMOCLAW_REASONING_EFFORT} \
NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} \
NEMOCLAW_INFERENCE_INPUTS=${NEMOCLAW_INFERENCE_INPUTS} \
NEMOCLAW_AGENT_TIMEOUT=${NEMOCLAW_AGENT_TIMEOUT} \
Expand Down
60 changes: 53 additions & 7 deletions docs/inference/configure-model-capabilities.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
# SPDX-License-Identifier: Apache-2.0
title: "Configure OpenClaw Model Capabilities"
sidebar-title: "Configure Model Capabilities"
description: "Declare reasoning mode and input modalities for an OpenClaw model in a NemoClaw sandbox."
description-agent: "Configures OpenClaw reasoning mode and text or image input support. Use when onboarding a reasoning or vision-capable model."
keywords: ["nemoclaw reasoning model", "nemoclaw vision model", "NEMOCLAW_INFERENCE_INPUTS"]
description: "Declare reasoning mode, reasoning effort, and input modalities for an OpenClaw model in a NemoClaw sandbox."
description-agent: "Configures OpenClaw reasoning mode, reasoning effort, and text or image input support. Use when onboarding a reasoning or vision-capable model."
keywords: ["nemoclaw reasoning model", "nemoclaw reasoning effort", "nemoclaw vision model"]
content:
type: "how_to"
---
Expand All @@ -26,6 +26,40 @@ nemoclaw onboard
For a compatible Anthropic endpoint, reasoning mode also skips the onboarding streaming check intended for models that emit normal response content.
Agent requests still use the streaming path, so confirm the endpoint's runtime behavior separately.

## Configure Reasoning Effort

Set `NEMOCLAW_REASONING_EFFORT` only when the provider is `compatible-endpoint` and the selected API is `openai-completions`.
The endpoint must accept an explicit reasoning budget.
The variable accepts `low`, `medium`, `high`, or `default`.
The default is unset, which leaves the endpoint's own default in place.

```bash
export NEMOCLAW_REASONING_EFFORT=high
nemoclaw onboard
```

NemoClaw applies the variable only to the `compatible-endpoint` provider.
Another provider clears it, even when that provider's route uses `openai-completions`.
On the `compatible-endpoint` provider, a value outside `low`, `medium`, `high`, and `default` fails before NemoClaw touches the provider, policies, the sandbox, or the registry.
Another provider clears the variable without reading it, so an invalid value neither applies nor fails.

`default` names the unset state, which is useful to clear an effort that a sandbox already records.

NemoClaw writes `params.extra_body.reasoning_effort` on the model entry in the built OpenClaw config.
OpenClaw merges that field into the request body.
NemoClaw does not add the field for another API family.
Reasoning effort is independent of `NEMOCLAW_REASONING`.
`NEMOCLAW_REASONING` declares that the model reasons, and `NEMOCLAW_REASONING_EFFORT` declares how much.

## Verify Reasoning Effort

NemoClaw reports the effective non-secret setting for a `compatible-endpoint` route that uses `openai-completions`.
During onboarding, `nemoclaw onboard --events=jsonl` includes `reasoningEffort` in each applicable event context.
The sandbox status output prints `Reasoning effort`, and `nemoclaw <sandbox-name> doctor --json` includes an informational `Inference` check labeled `Reasoning effort`.
An explicit override appears as `low`, `medium`, or `high`.
When the route uses the endpoint's own setting, these diagnostics report `endpoint-default`.
They omit the field or check for another provider or API family and never include endpoint credentials.

## Configure Image Input

Set `NEMOCLAW_INFERENCE_INPUTS=text,image` only when the model accepts image input through the selected provider.
Expand All @@ -42,14 +76,26 @@ Non-interactive onboarding uses the environment value or the default `text` sett
## Apply Capability Changes

These settings are build-time inputs.
Recreate an existing sandbox after changing either value.
Recreate an existing sandbox after changing any of these values.

```bash
nemoclaw onboard --fresh --name <sandbox-name> --recreate-sandbox
```

Onboarding records the reasoning flag in the sandbox's session and registry entry.
A resumed onboard and `nemoclaw <sandbox-name> rebuild` both replay that recorded value, so exporting `NEMOCLAW_REASONING` before either command does not change the flag.
When a resumed onboard sees an explicit `NEMOCLAW_REASONING` that disagrees with the recorded value, it reports the recorded value and the recreate command instead of applying the variable.
Onboarding records the reasoning flag and the reasoning effort in the sandbox's session and registry entry.
A resumed onboard and `nemoclaw <sandbox-name> rebuild` both replay those recorded values, so exporting `NEMOCLAW_REASONING` or `NEMOCLAW_REASONING_EFFORT` before either command does not change them.
When a resumed onboard on the `compatible-endpoint` provider sees an explicit `NEMOCLAW_REASONING` or `NEMOCLAW_REASONING_EFFORT` that disagrees with the recorded value, it reports the recorded value and the recreate command instead of applying the variable.

To change the reasoning effort on a running sandbox without a recreate, pass `--reasoning-effort` to `inference set`.

```bash
nemoclaw <sandbox-name> inference set --provider compatible-endpoint --model <model> --endpoint-url <recorded-url> --reasoning-effort high
```

Pass `--reasoning-effort default` to clear a recorded effort and return the endpoint to its own default.
`--reasoning-effort` overrides `NEMOCLAW_REASONING_EFFORT`.
When you omit the flag, `inference set` applies an exported `NEMOCLAW_REASONING_EFFORT`.
When neither is set, the sandbox keeps the recorded effort only while the resulting route still uses `compatible-endpoint` and `openai-completions`.
Switching to another provider or API family clears the recorded effort.

For context-window and output-token settings, refer to [Configure Model Limits](configure-model-limits).
9 changes: 9 additions & 0 deletions docs/inference/set-up-openai-compatible-endpoint.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,15 @@ NEMOCLAW_PROVIDER=custom \
| `NEMOCLAW_TRUSTED_PRIVATE_INFERENCE_HOSTS` | Optional comma-separated exact hostnames or IP literals for operator-owned private inference endpoints. Wildcards are not supported. |
| `COMPATIBLE_API_KEY` | Endpoint API key. Required unless loopback no-auth mode is selected. |

<AgentOnly variant="openclaw">

For OpenClaw, `NEMOCLAW_REASONING_EFFORT` accepts `low`, `medium`, `high`, or `default`.
A `low`, `medium`, or `high` value writes `params.extra_body.reasoning_effort` when the selected API is `openai-completions`.
Another API family omits the field.
An unset value or `default` leaves the endpoint's own default in place.

</AgentOnly>

Private and reserved addresses are blocked by default.
To use an inference gateway on a trusted corporate network, list only its exact host and keep the endpoint URL on that host:

Expand Down
29 changes: 28 additions & 1 deletion docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,8 @@ Each line is one JSON object with the version 1 envelope:

In this mode, human progress remains available on stderr so stdout stays valid JSONL.
Payloads contain only the existing bounded, redacted machine-event context: credential environment variable names may appear, but credential values and secret-bearing URL components are redacted.
For a `compatible-endpoint` route that uses `openai-completions`, the context includes `reasoningEffort` as `low`, `medium`, `high`, or `endpoint-default`.
Other provider and API-family routes omit this field.
Treat new event `type` values and new payload fields as additive changes.
A breaking envelope or field-semantics change increments `schemaVersion`.

Expand Down Expand Up @@ -1282,6 +1284,9 @@ Do not pass a sandbox name to `$$nemoclaw status`; that command is the global al
NemoClaw resolves the sandbox's recorded owning OpenShell gateway before querying live state.
If another gateway is active, it selects the owner and queries again instead of trusting a result from the sibling gateway.

For a `compatible-endpoint` route that uses `openai-completions`, the text output prints `Reasoning effort` as `low`, `medium`, `high`, or `endpoint-default`.
The line is omitted for another provider or API family.

Pass `--json` to emit a structured per-sandbox report instead of the text renderer.
The JSON output includes at least `schemaVersion`, `name`, `found`, `agent`, `agentDisplayName`, `agentRuntime`, `dcodeAutoApprovalMode`, `model`, `provider`, `recordedRoute`, `liveRoute`, `routeDrift`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, `policies`, `baselineExclusions`, `baselineExclusionStates`, `baselineExclusionTransition`, `failureLayer`, `terminalRuntimeHealth`, `servingProcessHealth`, and `dockerPaused`.
`baselineExclusions` is an array of exact baseline keys recorded for durable replay and is empty when the sandbox has none.
Expand Down Expand Up @@ -1482,6 +1487,9 @@ A live policy that contains the excluded key fails the check and requires policy
Warnings do not make the command fail.
Failed checks, including a failed or unavailable authoritative inference route, exit non-zero so scripts can use `doctor` as a readiness gate.
Use `--json` for machine-readable output.
For a `compatible-endpoint` route that uses `openai-completions`, the JSON report includes an informational `Inference` check labeled `Reasoning effort`.
The check reports `low`, `medium`, `high`, or `endpoint-default` and never includes credentials.
Because the check has `info` status, it does not change the command's exit status.

<AgentOnly variant="openclaw">

Expand Down Expand Up @@ -2672,7 +2680,7 @@ The command backs up workspace state, destroys the old sandbox (including its ho
Credentials are stripped from backups before storage.
Policy presets applied to the old sandbox are reapplied to the new one so your egress rules survive the rebuild.
Before creating the replacement sandbox, NemoClaw prints the finalized create-time policy scope whenever presets are included.
The replacement uses the recorded compatible-endpoint reasoning mode and web search selection instead of ambient shell values.
The replacement uses the recorded compatible-endpoint reasoning mode, reasoning effort, and web search selection instead of ambient shell values.
Rebuild preserves the recorded sandbox GPU enablement mode and, for an explicitly enabled sandbox, its recorded device selector.
It re-resolves the Docker-driver GPU route from the current host and current `NEMOCLAW_DOCKER_GPU_PATCH` value, so native-only, explicitly authorized native-with-fallback, and compatibility-only routing may differ from the original onboarding run.
A rebuild preserves the recorded tool-disclosure mode unless `--tool-disclosure` explicitly changes it; it ignores an ambient `NEMOCLAW_TOOL_DISCLOSURE` value while recreating the sandbox.
Expand Down Expand Up @@ -3181,6 +3189,24 @@ HTTPS IP-literal URLs remain supported and do not need the adapter.
NemoClaw accepts `http://host.openshell.internal:<port>` only with an explicit port from `1024` through `65535`; this narrow exception supports NemoClaw's sandbox-to-host inference routes and is not a general private-endpoint bypass.
`--credential-env` may also be supplied for compatible provider metadata; supported `--inference-api` values are `openai-completions`, `anthropic-messages`, and `openai-responses`.

</AgentOnly>
<AgentOnly variant="openclaw">

```bash
$$nemoclaw inference set --provider <provider> --model <model> [--sandbox <name>] [--no-verify] [--endpoint-url <url>] [--credential-env <ENV>] [--inference-api <api>] [--reasoning-effort <effort>]
```

`--reasoning-effort` accepts `low`, `medium`, `high`, or `default`.
The `low`, `medium`, and `high` values apply only to the `compatible-endpoint` provider.
NemoClaw rejects any other value before it changes the OpenShell route, the agent config, or the host registry.
For a `low`, `medium`, or `high` value on an `openai-completions` route, NemoClaw writes `params.extra_body.reasoning_effort` on the model entry, and OpenClaw merges it into the request body.
On another API family, NemoClaw removes an inherited `reasoning_effort` field and records the endpoint-default state.
`--reasoning-effort` overrides `NEMOCLAW_REASONING_EFFORT`.
When you omit the flag, `$$nemoclaw inference set` applies an exported `NEMOCLAW_REASONING_EFFORT`.
When neither is set, the sandbox keeps the recorded effort only while the resulting route uses `compatible-endpoint` and `openai-completions`.
Switching to another provider or API family clears the recorded effort.
Pass `default` to clear a recorded effort and return the endpoint to its own default.

</AgentOnly>
<AgentOnly variant="deepagents">

Expand Down Expand Up @@ -3604,6 +3630,7 @@ OpenClaw-specific onboarding configuration:
| `NEMOCLAW_CONTEXT_WINDOW` | positive integer (tokens) | Overrides the model's context-window value in the built OpenClaw config. |
| `NEMOCLAW_MAX_TOKENS` | positive integer (tokens) | Overrides the model's `maxTokens` in the built OpenClaw config. |
| `NEMOCLAW_REASONING` | `true` or `false` | Overrides the model's reasoning-mode flag in the built OpenClaw config. |
| `NEMOCLAW_REASONING_EFFORT` | `low`, `medium`, `high`, or `default` | Applies only to the `compatible-endpoint` provider. A `low`, `medium`, or `high` value writes `params.extra_body.reasoning_effort` when the selected API is `openai-completions`. Another API family omits the field. Unset leaves the endpoint's own default in place, and `default` clears a recorded effort. On `compatible-endpoint`, any other value fails before NemoClaw changes the provider, policies, sandbox, or registry. Another provider clears the variable without reading it. |
| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | duration with `s`, `m`, or `h` suffix (for example `30m`, `1h`, or `0m`) | Overrides `agents.defaults.heartbeat.every` in the built OpenClaw config. Set `0m` to disable periodic agent turns. |
| `NEMOCLAW_EXTRA_AGENTS_JSON` | JSON array of OpenClaw secondary-agent entries | Adds secondary agents to `agents.list`. Refer to [Extra OpenClaw agents](#extra-openclaw-agents) for the entry schema, path constraints, and validation rules. |

Expand Down
26 changes: 26 additions & 0 deletions scripts/generate-openclaw-config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -638,6 +638,29 @@ function coerceCompatDict(value: unknown): JsonObject {
throw new Error("NEMOCLAW_INFERENCE_COMPAT_B64 must decode to a JSON object or null");
}

const REASONING_EFFORT_VALUES = ["low", "medium", "high"];
const REASONING_EFFORT_DEFAULT = "default";
const REASONING_EFFORT_PROVIDER = "compatible-endpoint";

// OpenClaw merges params.extra_body into openai-completions request bodies, so
// this is the config-level route to a reasoning_effort the endpoint receives.
function buildReasoningEffortParams(env: Env): JsonObject {
const raw = (env.NEMOCLAW_REASONING_EFFORT || "").trim().toLowerCase();
const upstreamProvider = (env.NEMOCLAW_UPSTREAM_PROVIDER || "").trim();
if (!raw || raw === REASONING_EFFORT_DEFAULT) return {};
if (upstreamProvider !== REASONING_EFFORT_PROVIDER) return {};
if (!REASONING_EFFORT_VALUES.includes(raw)) {
throw new Error(
`NEMOCLAW_REASONING_EFFORT must be one of: ${[
...REASONING_EFFORT_VALUES,
REASONING_EFFORT_DEFAULT,
].join(", ")}`,
);
}
if ((env.NEMOCLAW_INFERENCE_API as string) !== "openai-completions") return {};
return { params: { extra_body: { reasoning_effort: raw } } };
}

// Canonical primary-agent entry. Always written first into agents.list, always
// flagged default: true. Pinning the slot here prevents the extra-agents env
// from displacing the primary agent: OpenClaw's resolveDefaultAgentId falls
Expand Down Expand Up @@ -1161,6 +1184,7 @@ export function buildConfig(env: Env = process.env): JsonObject {
const toolDisclosure = readToolDisclosureEnv(env);

const reasoning = (env.NEMOCLAW_REASONING || "false") === "true";
const reasoningEffortParams = buildReasoningEffortParams(env);
const inferenceInputs = (env.NEMOCLAW_INFERENCE_INPUTS || "text")
.split(",")
.map((value) => value.trim())
Expand Down Expand Up @@ -1302,6 +1326,7 @@ export function buildConfig(env: Env = process.env): JsonObject {
id: model,
name: primaryModelRef,
reasoning,
...reasoningEffortParams,
input: inferenceInputs,
cost: {
input: 0,
Expand Down Expand Up @@ -1337,6 +1362,7 @@ export function buildConfig(env: Env = process.env): JsonObject {
id: secondaryModelId,
name: ref,
reasoning,
...reasoningEffortParams,
input: inferenceInputs,
cost: {
input: 0,
Expand Down
Loading
Loading