nemoclaw-user-configure-inference

使用本地推理服务

注意事项

• Ollama 适合本地聊天，但在实际 Agent 负载下，某些模型与模板的组合可能会将工具调用作为纯文本返回。

先决条件

• 已安装 NemoClaw。
• 正在运行的本地模型服务，或 NemoClaw 入门向导可使用、启动或安装的受支持 Ollama、vLLM 或 NIM 配置。

NemoClaw 可以将推理请求路由到运行在你设备上的模型服务，而不是云 API。 本页介绍 Ollama、其他服务的兼容端点方案，以及 vLLM 和 NVIDIA NIM 的实验性托管选项。

所有方案都使用相同的 inference.local 路由模式。 沙盒中的 Agent 不会直接连接到你的模型服务。 OpenShell 会拦截推理流量，并将其转发到你配置的本地端点。

Ollama

Ollama 是默认的本地推理选项。 如果主机上已安装或正在运行 Ollama，入门向导会自动检测到它。

如果已安装 Ollama，但尚未运行，NemoClaw 会替你启动它。 在 macOS 和 Linux 上，如果未安装 Ollama，向导还可以提供安装选项。 如果主机上的 Ollama 版本低于 NemoClaw 对其入门模型的最低要求（当前为 0.7.0），向导会在提供商菜单中明确显示 升级 Ollama 选项，而不会悄悄沿用旧版守护进程；快速设置路径也会指向该选项。 向导会同时检查 CLI 二进制文件（ollama --version）和本地运行的守护进程（:11434 上的 /api/version），因此即使只有一方版本过旧，升级选项仍会显示。例如，用户本地安装的全新二进制文件可能与原有的系统守护进程配套运行。 如果通过 WSL 访问的是 Windows 主机上的 Ollama（地址为 host.docker.internal），则会跳过此检查；单独的 在 Windows 主机上使用 / 启动 / 安装 Ollama 选项会处理这种情况，并在 Windows 端执行相应操作。 在 macOS 上，向导会通过 brew upgrade ollama 执行平台安装或升级流程。 在 Linux 上，向导会执行官方的 https://ollama.com/install.sh 安装流程。 在 Linux 上升级时始终会使用由 sudo 驱动的系统级流程，因为不使用 sudo 的用户本地安装回退方案会导致现有的系统守护进程继续在 :11434 上提供旧版二进制文件。 如果在非交互式运行中无法使用 sudo，NemoClaw 不会悄悄改用较低权限的流程，而是会要求你以交互方式重新运行，或手动升级 Ollama。 升级完成后，NemoClaw 会重新检查运行中守护进程的 /api/version，如果守护进程报告的版本仍低于最低要求，运行就会失败。 全新安装会跳过此项重新检查，因为随附的安装程序会安装达到或高于最低要求的守护进程。 在 WSL 上，向导可以通过 PowerShell 互操作，在 Windows 主机上使用、启动、重启或安装 Ollama。

Linux 安装模式

在原生 Linux 上，安装路径会在系统安装（安装在 /usr/local 下，通过官方 https://ollama.com/install.sh）和无需 sudo 的用户本地安装（安装在 ${HOME}/.local 下）之间进行选择。 NemoClaw 会自动选择模式：

• 以 root 身份运行或拥有免密码 sudo（sudo -n true 返回 0）时，选择系统安装。
• 非交互式运行（NEMOCLAW_NON_INTERACTIVE=1 或 stdin 没有 TTY）且没有免密码 sudo 时，选择用户本地安装。 此路径可让无头主机完成引导流程，而无需提示输入 sudo 密码。
• 交互式 shell 且没有免密码 sudo 时，选择系统安装，并像往常一样让官方安装程序提示输入密码。

使用 NEMOCLAW_OLLAMA_INSTALL_MODE=system 或 NEMOCLAW_OLLAMA_INSTALL_MODE=user 覆盖自动检测结果。

用户本地安装仅复现官方安装程序中的二进制文件解压步骤。 它会下载发行版 tarball，将其解压到 ${HOME}/.local，并启动一次 ${HOME}/.local/bin/ollama serve。 它不会配置 systemd 服务、不会创建 ollama 系统用户，也不会安装 CUDA 驱动，因此重启后必须手动重新启动守护进程。 如果 ${HOME}/.local/bin 尚未加入 PATH，NemoClaw 还会打印一行 PATH 提示；你可以将 export PATH="${HOME}/.local/bin:$PATH" 添加到 shell 配置文件，以便直接调用 ollama。

两种模式都依赖 zstd 来解压归档文件。在 Debian 和 Ubuntu 上，系统安装路径会使用 sudo apt-get 自动安装 zstd，并在继续之前说明安装提示。 用户本地安装路径无法在没有提权的情况下安装系统软件包，因此如果缺少 zstd，它会打印各发行版对应的安装提示并退出；请手动安装 zstd，然后重新运行引导流程。

运行引导向导。

$ nemoclaw onboard

从提供方列表中选择 Local Ollama。 NemoClaw 会列出已安装的模型；如果尚未安装任何模型，则会提供入门模型。 如果主机当前可用的 GPU 内存足以容纳较大的入门模型，入门模型列表会包含 qwen3.6:35b，并默认选择该模型。 如果引导时有其他 GPU 工作负载占用了大部分内存，NemoClaw 会将菜单调整为仍可容纳的最大模型。 它会拉取所选模型，将其加载到内存中，并在继续之前进行验证。 当 Ollama 报告已加载模型的上下文长度时，NemoClaw 会将该值用于写入 openclaw.json 的 contextWindow，除非你自行设置了 NEMOCLAW_CONTEXT_WINDOW。 如果所选模型声明不支持工具调用，引导流程会停止，并提示选择 ollama show <model> 能力中包含 tools 的模型。 验证还要求支持结构化的聊天补全工具调用。 如果模型将工具调用 JSON 泄露为普通消息文本，引导流程会停止，以便你选择能够在预期响应字段中返回工具调用的模型。 在 WSL 上，如果你选择 Windows 主机 Ollama 路径，NemoClaw 会使用 host.docker.internal:11434，并通过 Ollama HTTP API 拉取缺失的模型，而不要求在 WSL 内安装 ollama CLI。

使用 Windows 主机上的 Ollama 配合 WSL

当 NemoClaw 在 WSL 中运行时，提供方菜单可以包含 Windows 主机上的 Ollama 操作：

• 当 Windows 守护进程已可访问时，使用 Windows 主机上的 Ollama。
• 当守护进程已安装但仅绑定到 Windows 回环地址时，重启 Windows 主机上的 Ollama。
• 当 Ollama 已安装但尚未运行时，在 Windows 主机上启动 Ollama。
• 当 Windows 尚未安装 Ollama 时，在 Windows 主机上安装 Ollama。

安装和重启操作会在 Windows 端设置 OLLAMA_HOST=0.0.0.0:11434，以便 Docker 和 WSL 通过 host.docker.internal 访问守护进程。 执行安装或重启操作后，NemoClaw 会从检测到的 Windows 托盘应用或已验证的 ollama.exe 路径重新启动 Ollama，并等待 host.docker.internal:11434 响应。

如果 HTTP 端点尚不可访问，NemoClaw 还会通过 PowerShell 互操作检查 Windows 的 ollama.exe 进程，以便提供启动或重启操作，而不是隐藏 Windows 主机选项。 如果守护进程仍无法访问，设置流程会打印 PowerShell 命令，供你检查 Windows 端的进程和端口状态。每次仅使用一个运行在端口 11434 上的 Ollama 实例。 如果 WSL 和 Windows 主机上的 Ollama 都在运行，请在设置过程中选择预期的菜单项，以便 NemoClaw 针对正确的守护进程验证并拉取模型。

警告：

Ollama 便于本地聊天，但在实际 Agent 负载下，某些模型和模板组合可能会将工具调用作为纯文本返回。如果 TUI 显示原始 JSON（例如 {"name":"memory_search","arguments":{...}}），而不是运行工具，请切换到 vLLM，并使用 --enable-auto-tool-choice 和正确的 --tool-call-parser。请参阅工具调用可靠性。

身份验证反向代理

在非 WSL 主机上，NemoClaw 会让 Ollama 绑定到 127.0.0.1:11434，并在 0.0.0.0:11435 上启动由令牌保护的反向代理。 原生安装和启动流程也会将 NemoClaw 管理的 systemd 启动配置重置为环回绑定。 容器和本地网络中的其他主机只能通过代理访问 Ollama，代理会先验证 Bearer 令牌，再转发请求。 在这条原生路径上，NemoClaw 绝不会在未经身份验证的情况下暴露 Ollama。

WSL Ollama 路径不使用此代理。 Windows 主机上的 Ollama 使用 Windows 守护进程，并通过 host.docker.internal 访问。

对于非 WSL 的 Ollama 配置，引导向导会自动管理代理：

• 首次运行时生成一个随机的 24 字节令牌，并以 0600 权限将其存储在 ~/.nemoclaw/ollama-proxy-token 中。
• 在 Ollama 启动后启动代理，并在继续之前验证代理。
• 清理之前运行时遗留的代理进程。
• 在确定推理路由之前，探测从沙箱 Docker 网络到代理的路径。
• 卸载时，在删除 NemoClaw 状态之前停止匹配的代理进程。
• 主机重启后复用已持久化的令牌，因此无需重新运行 onboard。

在原生 Linux 主机上，防火墙可能允许主机代理健康检查通过，但仍会阻止沙箱容器访问 OpenShell Docker 网桥。 当沙箱侧代理探测因 TCP 错误而失败时，引导会在保存推理路由之前退出，并打印类似以下的命令：

$ sudo ufw allow from <openshell-docker-subnet> to any port 11435 proto tcp
$ nemoclaw onboard

如果无法执行探测（例如 Docker Desktop 或 WSL 使用了不同的主机路由模型），引导会继续，并依赖常规代理健康检查。

沙箱提供程序配置为使用代理端口 11435，并将生成的令牌用作其 OPENAI_API_KEY 凭据。 OpenShell 的 L7 代理会在出站时注入令牌，因此沙箱内的 Agent 不会直接看到令牌。

所有代理端点都要求提供 Bearer 令牌，包括 GET /api/tags。 通过代理执行的内部健康和连通性检查会将任何 HTTP 响应（包括 401）视为代理正常运行的证明——只有完全没有响应时才会判定失败。

如果启动 onboard 时 Ollama 已在非环回地址上运行，向导会将其重启并绑定到 127.0.0.1:11434，确保代理是访问模型服务的唯一网络路径。

GPU 内存清理

切换离开 Ollama、停止主机服务或销毁由 Ollama 提供支持的沙箱时，NemoClaw 会请求 Ollama 从 GPU 内存中卸载当前已加载的模型。 清理操作会为 Ollama 报告的每个模型发送 keep_alive: 0，并尽力执行，因此即使 Ollama 已停止，关闭流程也会继续。 此操作不会删除已下载的模型文件。

加载 references/use-local-inference-details.md，了解非交互式设置的详细步骤。

OpenAI 兼容服务

此选项适用于任何实现了 /v1/chat/completions 的服务，包括 vLLM、TensorRT-LLM、llama.cpp、LocalAI 等。 对于兼容的端点，NemoClaw 默认使用 /v1/chat/completions。 这样可以避免一类故障：本地后端接受 /v1/responses 请求，却静默丢弃系统提示词和工具定义。 如需使用 /v1/responses，请在运行 onboard 前设置 NEMOCLAW_PREFERRED_API=openai-responses。

启动模型服务。 以下示例使用 vLLM，但任何兼容 OpenAI 的服务都可使用。

$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

运行 onboard 向导。

$ nemoclaw onboard

当向导提示你选择推理提供方时，选择 Other OpenAI-compatible endpoint。 输入本地服务的基础 URL，例如 http://localhost:8000/v1。

向导会提示输入 API 密钥。 如果你的服务不需要身份验证，请输入任意非空字符串（例如 dummy）。

NemoClaw 会在继续之前发送测试推理请求，以验证端点。 对于兼容端点提供方，向导默认探测 /v1/chat/completions。 如果设置了 NEMOCLAW_PREFERRED_API=openai-responses，NemoClaw 会改为探测 /v1/responses，并且只有当响应包含 OpenClaw 所需的流式事件时才会选择该接口。 如果推理模型在生成最终答案之前只返回推理内容，NemoClaw 会使用更大的响应预算重试冒烟测试请求。 路由、配置和身份验证失败仍会立即报错。

加载 references/use-local-inference-details.md，查看非交互式设置和选择 API 路径的详细步骤。

Anthropic 兼容服务

加载 references/use-local-inference-details.md 查看详细步骤。

vLLM

如果 vLLM 已在 localhost:8000 上运行，NemoClaw 可以自动检测它，并查询 /v1/models 端点以确定已加载的模型。 在配备 NVIDIA GPU 的受支持 Linux 主机上，onboard 向导还可以为你安装或启动托管的 vLLM 容器。

对于已在运行的 vLLM 服务，请运行 nemoclaw onboard，并从提供方列表中选择 Local vLLM [experimental]。

$ nemoclaw onboard

如果 vLLM 已在运行，NemoClaw 会检测正在运行的模型并验证端点。 如果 vLLM 未运行，且主机符合 DGX Spark 或 DGX Station 托管配置，NemoClaw 默认会显示 Install vLLM 或 Start vLLM 条目。 通用 Linux NVIDIA GPU 主机仍需先设置 NEMOCLAW_EXPERIMENTAL=1 或 NEMOCLAW_PROVIDER=install-vllm，托管条目才会显示。 NemoClaw 会拉取 vLLM 镜像，将模型权重下载到 ~/.cache/huggingface，在 localhost:8000 上启动 nemoclaw-vllm 容器，并在模型加载时输出进度标记。 首次运行可能需要 10 到 30 分钟。 后续运行会复用缓存的镜像和模型权重。

托管的 vLLM 使用以下配置：

主机配置	默认模型
DGX Spark	Qwen/Qwen3.6-27B-FP8
DGX Station	Qwen/Qwen3.6-27B-FP8
配备 NVIDIA GPU 的 Linux	nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8

注意：

NemoClaw 会强制 vLLM 使用 chat/completions API 路径。 vLLM 的 /v1/responses 端点不会运行 --tool-call-parser，因此工具调用会以原始文本形式传入。

加载 references/use-local-inference-details.md，查看非交互式设置和覆盖托管 vLLM 模型的详细步骤。

NVIDIA NIM（实验性）

NemoClaw 可在配备支持 NIM 的 NVIDIA GPU 的主机上拉取、启动并管理 NIM 容器。

设置实验性标志并运行 onboard。

$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard

从提供方列表中选择 Local NVIDIA NIM [experimental]。 NemoClaw 会根据 GPU 显存筛选可用模型，拉取 NIM 容器镜像、启动容器，并等待容器运行正常后再继续。 在配备多种 NVIDIA GPU 型号的主机上，预检摘要会显示检测到的每种 GPU 型号和总显存，以便你确认模型选择使用的设备类别。

NIM 容器镜像托管在 nvcr.io 上，执行 docker pull 前需要进行 NGC 注册表身份验证。 如果 Docker 尚未登录 nvcr.io，onboard 会提示输入 NGC API 密钥，并通过 --password-stdin 运行 docker login nvcr.io，确保密钥不会写入磁盘或 Shell 历史记录。 输入时，提示会隐藏密钥；如果密钥无效，会重试一次，之后才报错退出。 在非交互模式下，如果 Docker 尚未完成身份验证，onboard 会退出并显示登录说明；请自行运行 docker login nvcr.io，然后重新运行 nemoclaw onboard --non-interactive。 如果已导出 NGC_API_KEY 或 NVIDIA_API_KEY，NemoClaw 会通过进程环境将其传入托管的 NIM 容器，而不是使用命令行参数。 如果 NIM 容器在健康检查端点就绪前退出，onboard 会提前停止并打印容器日志的最后几行。

注意：

NIM 内部使用 vLLM。 同样适用 chat/completions API 路径限制。

加载 references/use-local-inference-details.md，查看非交互式设置的详细步骤。

超时配置

加载 references/use-local-inference-details.md，查看详细步骤。

验证配置

加载 references/use-local-inference-details.md，查看详细步骤。

在运行时切换模型

加载 references/use-local-inference-details.md，查看详细步骤。

参考资料

• 切换推理提供方、更改模型运行时或重新配置推理路由时，加载 references/switch-inference-providers.md。 无需重启沙盒即可更改当前使用的推理模型。
• 用户询问如何添加第二个模型、配置子 Agent 模型、使用 Omni 执行视觉任务、配置 agents.list，或在 NemoClaw 中使用 sessions_spawn 时，加载 references/set-up-sub-agent.md。 其中介绍了添加辅助 OpenClaw 子 Agent 模型时 NemoClaw 特有的文件路径和更新流程。
• references/tool-calling-reliability.md — 说明 Ollama 工具调用泄漏的症状、建议使用带工具调用解析器的 vLLM 的情况，以及如何将 NemoClaw 指向支持解析器的本地端点。
• 解释有哪些可用提供方、onboard 向导会显示什么内容，或推理路由如何工作时，加载 references/inference-options.md。 其中列出了 NemoClaw 引导设置期间提供的所有推理提供方。
• 需要了解非交互式设置、选择 API 路径、兼容 Anthropic 的服务及相关详情时，加载 references/use-local-inference-details.md。

相关技能

• Inference Options：查看引导设置期间可用提供方的完整列表。
• Tool-Calling Reliability：诊断本地模型输出原始 JSON 工具调用内容的问题。
• Switch Inference Models：在运行时切换模型。
• nemoclaw-user-get-started — 快速入门（使用 nemoclaw-user-get-started 技能）适用于首次安装