AI 提供商

本页介绍如何为 OpenClaw 配置推理提供商——从 OpenRouter 和 Anthropic 等云 API，到 Ollama 和 vLLM 等自托管端点，再到高级路由和降级配置。使用 OpenClaw 至少需要配置一个提供商。

推理提供商

您需要至少一种方式连接到大语言模型（LLM）。可使用 openclaw model 命令交互式切换提供商和模型，或直接进行配置：

提供商	设置方式
Nous Portal	`openclaw model`（OAuth，订阅制）
OpenAI Codex	`openclaw model`（ChatGPT OAuth，使用 Codex 模型）
GitHub Copilot	`openclaw model`（OAuth 设备码流程，`COPILOT_GITHUB_TOKEN`、`GH_TOKEN` 或 `gh auth token`）
GitHub Copilot ACP	`openclaw model`（启动本地 `copilot --acp --stdio`）
Anthropic	`openclaw model`（通过 Claude Code 认证使用 Claude Pro/Max，或 Anthropic API 密钥，或手动设置令牌）
OpenRouter	在 `~/.hermes/.env` 中设置 `OPENROUTER_API_KEY`
AI Gateway	在 `~/.hermes/.env` 中设置 `AI_GATEWAY_API_KEY`（提供者：`ai-gateway`）
z.ai / GLM	在 `~/.hermes/.env` 中设置 `GLM_API_KEY`（提供者：`zai`）
Kimi / Moonshot	在 `~/.hermes/.env` 中设置 `KIMI_API_KEY`（提供者：`kimi-coding`）
MiniMax	在 `~/.hermes/.env` 中设置 `MINIMAX_API_KEY`（提供者：`minimax`）
MiniMax 中国区	在 `~/.hermes/.env` 中设置 `MINIMAX_CN_API_KEY`（提供者：`minimax-cn`）
阿里云	在 `~/.hermes/.env` 中设置 `DASHSCOPE_API_KEY`（提供者：`alibaba`，别名：`dashscope`、`qwen`）
Kilo Code	在 `~/.hermes/.env` 中设置 `KILOCODE_API_KEY`（提供者：`kilocode`）
OpenCode Zen	在 `~/.hermes/.env` 中设置 `OPENCODE_ZEN_API_KEY`（提供者：`opencode-zen`）
OpenCode Go	在 `~/.hermes/.env` 中设置 `OPENCODE_GO_API_KEY`（提供者：`opencode-go`）
DeepSeek	在 `~/.hermes/.env` 中设置 `DEEPSEEK_API_KEY`（提供者：`deepseek`）
Hugging Face	在 `~/.hermes/.env` 中设置 `HF_TOKEN`（提供者：`huggingface`，别名：`hf`）
Google / Gemini	在 `~/.hermes/.env` 中设置 `GOOGLE_API_KEY`（或 `GEMINI_API_KEY`）（提供者：`gemini`）
自定义端点	`openclaw model` → 选择“自定义端点”（保存在 `config.yaml` 中）

模型密钥别名

在 model: 配置节中，您可以使用 default: 或 model: 作为模型 ID 的键名。model: { default: my-model } 和 model: { model: my-model } 两种写法效果完全相同。

Codex 说明

OpenAI Codex 提供商通过设备码进行认证（打开一个 URL，输入代码）。OpenClaw 将生成的凭据存储在自己的认证存储中，路径为 ~/.hermes/auth.json，并且当存在时可从 ~/.codex/auth.json 导入现有的 Codex CLI 凭据。无需安装 Codex CLI。

注意

即使使用 Nous Portal、Codex 或自定义端点，某些工具（如视觉、网页摘要、MoA）仍会使用一个独立的“辅助”模型——默认通过 OpenRouter 使用 Gemini Flash。设置 OPENROUTER_API_KEY 可自动启用这些工具。您也可以配置这些工具使用的模型和提供商——详见辅助模型。

Anthropic（原生）

直接通过 Anthropic API 使用 Claude 模型——无需 OpenRouter Agent。支持三种认证方式：

# 使用 API 密钥（按 token 付费）
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# 首选：通过“0”进行身份验证
# OpenClaw 将在可用时直接使用 Claude Code 的凭证存储
openclaw model

# 使用设置令牌手动覆盖（后备“0”遗留）
export ANTHROPIC_TOKEN=***  # setup-token 或手动 OAuth token
hermes chat --provider anthropic

# 自动检测 Claude Code 凭证（如果您已经使用 Claude Code）
hermes chat --provider anthropic  # 自动读取Claude Code凭证文件

当通过 openclaw model 选择 Anthropic OAuth 时，OpenClaw 优先使用 Claude Code 自身的凭证存储，而不是将令牌复制到 ~/.hermes/.env。这能保持可刷新的 Claude 凭证持续可刷新。

或永久设置：

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

别名

--provider claude 和 --provider claude-code 也可作为 --provider anthropic 的简写。

GitHub Copilot

OpenClaw 将 GitHub Copilot 作为一级提供商支持，提供两种模式：

copilot —— 直接使用 Copilot API（推荐）。利用您的 GitHub Copilot 订阅，通过 Copilot API 访问 GPT-5.x、Claude、Gemini 等多种模型。

hermes chat --provider copilot --model gpt-5.4

认证选项（按以下顺序检查）：

COPILOT_GITHUB_TOKEN 环境变量
GH_TOKEN 环境变量
GITHUB_TOKEN 环境变量
gh auth token CLI 回退

如果未找到令牌，openclaw model 将提供 OAuth 设备码登录——与 Copilot CLI 和 opencode 使用相同的流程。

令牌类型

Copilot API 不支持传统的个人访问令牌（ghp_*）。支持的令牌类型：

类型	前缀	获取方式
OAuth 令牌	`gho_`	`openclaw model` → GitHub Copilot → 使用 GitHub 登录
细粒度 PAT	`github_pat_`	GitHub 设置 → 开发者设置 → 细粒度令牌（需具备 Copilot Requests 权限）
GitHub App 令牌	`ghu_`	通过 GitHub App 安装获取

如果您的 gh auth token 返回的是 ghp_* 令牌，请使用 openclaw model 通过 OAuth 进行认证。

API 路由：GPT-5+ 模型（除 gpt-5-mini 外）自动使用 Responses API。其余所有模型（GPT-4o、Claude、Gemini 等）使用 Chat Completions。模型会从实时 Copilot 目录中自动检测。

copilot-acp —— Copilot ACP Agent 后端。作为子进程启动本地 Copilot CLI：

hermes chat --provider copilot-acp --model copilot-acp
# 需要 PATH 中的 GitHub Copilot CLI 和现有的 `copilot login` session

永久配置：

model:
  provider: "copilot"
  default: "gpt-5.4"

环境变量	说明
`COPILOT_GITHUB_TOKEN`	Copilot API 的 GitHub 令牌（优先级最高）
`OPENCLAW_COPILOT_ACP_COMMAND`	覆盖 Copilot CLI 二进制文件路径（默认：`copilot`）
`OPENCLAW_COPILOT_ACP_ARGS`	覆盖 ACP 参数（默认：`--acp --stdio`）

一级中文 AI 服务商

这些服务商已内置支持，并拥有专用的提供者 ID。设置 API 密钥后，使用 --provider 选择：

# z.ai / 智普AI GLM
hermes chat --provider zai --model glm-5
# 要求：“0”中的“1”

# 基米 / 登月人工智能
hermes chat --provider kimi-coding --model kimi-for-coding
# 要求：“0”中的“1”

# MiniMax（全局端点）
hermes chat --provider minimax --model MiniMax-M2.7
# 要求：“0”中的“1”

# MiniMax（中国端点）
hermes chat --provider minimax-cn --model MiniMax-M2.7
# 要求：“0”中的“1”

# 阿里云 / DashScope (Qwen models)
hermes chat --provider alibaba --model qwen3.5-plus
# 要求：“0”中的“1”

或在 config.yaml 中永久设置提供者：

model:
  provider: "zai"       # 或：kimi编码、minimax、minimax-cn、阿里巴巴
  default: "glm-5"

可通过 GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL 或 DASHSCOPE_BASE_URL 环境变量覆盖基础 URL。

Z.AI 端点自动检测

使用 Z.AI / GLM 提供者时，OpenClaw 会自动探测多个端点（全球、中国、代码专用变体），以找到可接受你 API 密钥的端点。你无需手动设置 GLM_BASE_URL —— 工作中的端点将被自动探测并缓存。

xAI (Grok) 提示缓存

当使用 xAI 作为提供者（任何包含 x.ai 的基础 URL）时，OpenClaw 会自动启用提示缓存，通过在每个 API 请求中发送 x-grok-conv-id 头部来实现。这会将请求路由到会话期间的同一服务器，使 xAI 的基础设施能够重用缓存的系统提示和对话历史。

无需任何配置 —— 只要检测到 xAI 端点且存在会话 ID，缓存就会自动激活。这可显著降低多轮对话的延迟和成本。

Hugging Face 推理提供者

Hugging Face 推理提供者通过统一的 OpenAI 兼容端点（router.huggingface.co/v1）将请求路由至 20 多个开源模型。请求会自动路由到最快可用的后端（如 Groq、Together、SambaNova 等），并支持自动故障转移。

# 使用任何可用的 model
hermes chat --provider huggingface --model Qwen/Qwen3-235B-A22B-Thinking-2507
# 要求：“0”中的“1”

# 短别名
hermes chat --provider hf --model deepseek-ai/DeepSeek-V3.2

或在 config.yaml 中永久设置：

model:
  provider: "huggingface"
  default: "Qwen/Qwen3-235B-A22B-Thinking-2507"

在 huggingface.co/settings/tokens 获取你的令牌 —— 确保启用“对推理提供者发起调用”权限。免费套餐包含（每月 $0.10 信用额度，提供方费率无加价）。

你可以在模型名称后附加路由后缀：:fastest（默认）、:cheapest，或 :provider_name 以强制使用特定后端。

基础 URL 可通过 HF_BASE_URL 覆盖。

自定义与自托管 LLM 提供商

OpenClaw 可与 任何 OpenAI 兼容的 API 端点 配合使用。只要服务器实现了 /v1/chat/completions，你就可以将其指向 OpenClaw。这意味着你可以使用本地模型、GPU 推理服务器、多提供者路由器或任何第三方 API。

通用设置

配置自定义端点的三种方式：

交互式设置（推荐）：

openclaw model
# 选择“0”
# 输入：API 底座 URL、API 密钥、Model 名称

手动配置（config.yaml）：

# 在“0”中
model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

旧版环境变量

.env 中的 OPENAI_BASE_URL 和 LLM_MODEL 已移除。OpenClaw 的任何部分均不再读取它们 —— config.yaml 是模型和端点配置的唯一来源。如果你的 .env 中存在过时条目，将在下次执行 openclaw setup 或配置迁移时自动清除。请使用 openclaw model 或直接编辑 config.yaml。

两种方法均会持久化至 config.yaml，该文件是模型、提供者和基础 URL 的唯一真相来源。

使用 `/model` 切换模型

自定义端点配置完成后，你可以在会话中随时切换模型：

/model custom:qwen-2.5          # 在您的自定义端点上切换到 model
/model custom                    # 从端点自动检测model
/model openrouter:claude-sonnet-4 # 切换回云端 provider

如果你已配置了命名的自定义提供者（见下文），请使用三重语法：

/model custom:local:qwen-2.5    # 使用“0”自定义“1”和“2”“3”-2.5
/model custom:work:llama3       # 将 "work" 自定义 Provider 与 llama3 一起使用

切换提供者时，OpenClaw 会将基础 URL 和提供者持久化到配置中，确保更改在重启后仍然有效。当从自定义端点切换到内置提供者时，过时的基础 URL 会自动清除。

提示

/model custom（无模型名称）会查询你的端点的 /models API，并在仅加载一个模型时自动选择该模型。适用于运行单个模型的本地服务器。

以下所有操作均遵循相同模式 —— 只需更改 URL、密钥和模型名称即可。

Ollama — 本地模型，零配置

Ollama 通过一条命令即可在本地运行开源权重模型。适用于：快速本地实验、对隐私敏感的工作、离线使用。支持通过 OpenAI 兼容 API 调用工具。

# 安装并运行 model
ollama pull qwen2.5-coder:32b
ollama serve   # 在端口 11434 上启动

然后配置 OpenClaw：

openclaw model
# 选择“0”
# 输入“1”：“0”
# 跳过API密钥（Ollama不需要）
# 输入 模型 名称（例如 qwen2.5-coder:32b）

或直接配置 config.yaml：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768   # 请参阅下面的警告

Ollama 默认上下文长度极低

Ollama 不会默认使用模型的完整上下文窗口。根据你的显存情况，默认值如下：

可用显存	默认上下文
少于 24 GB	4,096 个 token
24–48 GB	32,768 个 token
48 GB 以上	256,000 个 token

对于需要工具调用的 Agent 使用，至少需要 16k–32k 的上下文。在 4k 时，系统提示 + 工具模式本身可能就填满窗口，导致没有空间用于对话。

如何增加上下文长度（任选其一）：

# 选项 1：通过环境变量设置服务器范围（推荐）
OLLAMA_CONTEXT_LENGTH=32768 ollama serve

# 选项 2：对于 systemd 管理的 Ollama
sudo systemctl edit ollama.service
# 添加：环境="OLLAMA_CONTEXT_LENGTH=32768"
# 然后： sudo systemctl daemon-reload && sudo systemctl restart ollama

# 选项 3：将其烘焙为自定义 模型（持久 per-模型）
echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 32768" > Modelfile
ollama create qwen2.5-coder-32k -f Modelfile

你无法通过 OpenAI 兼容 API（/v1/chat/completions）设置上下文长度。必须在服务器端或通过 Modelfile 进行配置。这是将 Ollama 与 OpenClaw 等工具集成时最常见的困惑来源。

验证你的上下文长度是否正确设置：

ollama ps
# 查看 CONTEXT 列 — 它应该显示您的配置值

提示

使用 ollama list 查看可用模型。通过 ollama pull <model> 从 Ollama 库下载任意模型。Ollama 会自动处理 GPU 分载——大多数设置无需额外配置。

vLLM — 高性能 GPU 推理

vLLM 是生产环境 LLM 服务的标准选择。适用于：在 GPU 硬件上实现最大吞吐量、服务大模型、连续批处理。

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

然后配置 OpenClaw：

openclaw model
# 选择“0”
# 输入网址：http://localhost:8000/v1
# 跳过 API 密钥（如果您用 --api-key 配置了 vLLM，则输入 1）
# 输入模型名称：meta-flame/Llama-3.1-70B-Instruct

上下文长度：vLLM 默认读取模型的 max_position_embeddings。如果超过 GPU 内存，会报错并提示你降低 --max-model-len。你也可以使用 --max-model-len auto 自动找出能适配的最大值。设置 --gpu-memory-utilization 0.95（默认为 0.9）可进一步压缩上下文以节省显存。

工具调用需要显式启用标志：

标志	用途
`--enable-auto-tool-choice`	用于支持 `tool_choice: "auto"`（OpenClaw 中的默认行为）
`--tool-call-parser <name>`	模型工具调用格式的解析器

支持的解析器：openclaw（Qwen 2.5，OpenClaw 2/3）、llama3_json（Llama 3.x）、mistral、deepseek_v3、deepseek_v31、xlam、pythonic。若未使用这些标志，工具调用将无法工作——模型会将工具调用输出为文本。

提示

vLLM 支持人类可读的大小单位：--max-model-len 64k（小写 k = 1000，大写 K = 1024）。

SGLang — 基于 RadixAttention 的快速服务

SGLang 是 vLLM 的替代方案，采用 RadixAttention 实现 KV 缓存复用。适用于：多轮对话（前缀缓存）、约束解码、结构化输出。

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

然后配置 OpenClaw：

openclaw model
# 选择“0”
# 输入“1”：“0”
# 输入模型名称：meta-flame/Llama-3.1-70B-Instruct

上下文长度：SGLang 默认从模型配置中读取。可使用 --context-length 覆盖。若需超过模型声明的最大值，请设置 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1。

工具调用：使用 --tool-call-parser 并配合对应模型家族的解析器：qwen（Qwen 2.5）、llama3、llama4、deepseekv3、mistral、glm。缺少此标志时，工具调用将以纯文本形式返回。

SGLang 默认最大输出 token 数为 128

如果响应看起来被截断，请在请求中添加 max_tokens，或在服务器上设置 --default-max-tokens。若请求中未指定，SGLang 的默认值仅为每响应 128 个 token。

llama.cpp / llama-server — CPU 与 Metal 推理

llama.cpp 可在 CPU、Apple Silicon（Metal）和消费级 GPU 上运行量化模型。适用于：无需数据中心 GPU 运行模型、Mac 用户、边缘部署。

# 构建并启动llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

上下文长度（-c）：近期版本默认值为 0，表示从 GGUF 元数据中读取模型训练时的上下文长度。对于训练上下文超过 128k 的模型，这可能导致内存溢出（OOM），因尝试分配完整的 KV 缓存。请显式设置 -c 为所需值（32k–64k 是 Agent 使用的好范围）。若使用并行槽位（-np），总上下文将分配给各槽位——例如 -c 32768 -np 4 时，每个槽位仅获得 8k。

然后配置 OpenClaw 指向它：

openclaw model
# 选择“0”
# 输入“1”：“0”
# 跳过API密钥（本地服务器不需要）
# 输入 model 名称 — 或留空以自动检测是否仅加载一个 model

这会将端点保存至 config.yaml，以在会话间持久化。

--jinja 对工具调用是必需的

若缺少 --jinja，llama-server 会完全忽略 tools 参数。模型会尝试在响应文本中写入 JSON 形式的工具调用，但 OpenClaw 无法识别为工具调用——你将看到原始 JSON 如 {"name": "web_search", ...} 作为消息打印，而非实际搜索。

原生工具调用支持（最佳性能）：Llama 3.x、Qwen 2.5（含 Coder）、OpenClaw 2/3、Mistral、DeepSeek、Functionary。其他所有模型使用通用处理器，虽可用但效率较低。完整支持列表请参见 llama.cpp 函数调用文档。

可通过检查 http://localhost:8080/props 验证工具支持是否启用——chat_template 字段应存在。

提示

从 Hugging Face 下载 GGUF 模型。Q4_K_M 量化格式在质量与内存占用之间提供了最佳平衡。

LM Studio — 带本地模型的桌面应用

LM Studio 是一款带有图形界面的桌面应用程序，用于运行本地模型。适用于：偏好可视化界面的用户、快速测试模型、macOS/Windows/Linux 上的开发者。

从 LM Studio 应用启动服务器（开发者选项卡 → 启动服务器），或使用命令行：

lms server start                        # 在端口 1234 上启动
lms load qwen2.5-coder --context-length 32768

然后配置 OpenClaw：

openclaw model
# 选择“0”
# 输入“1”：“0”
# 跳过API密钥（LM Studio不需要）
# 输入model名称

上下文长度默认值通常为 2048

LM Studio 会从模型元数据中读取上下文长度，但许多 GGUF 模型报告的默认值较低（2048 或 4096）。请始终在 LM Studio 模型设置中显式设置上下文长度：

点击模型选择器旁边的齿轮图标
将“上下文长度”设置为至少 16384（建议设置为 32768）
重新加载模型以使更改生效

或者使用命令行：lms load model-name --context-length 32768

要为每个模型设置持久化默认值：我的模型标签页 → 模型旁边的齿轮图标 → 设置上下文大小。

工具调用：自 LM Studio 0.3.6 起支持。经过原生工具调用训练的模型（如 Qwen 2.5、Llama 3.x、Mistral、OpenClaw）会自动检测并显示工具徽章。其他模型将使用通用回退方案，可能可靠性较低。

WSL2 网络配置（Windows 用户）

由于 OpenClaw 需要 Unix 环境，Windows 用户需在 WSL2 中运行它。如果你的模型服务器（Ollama、LM Studio 等）运行在 Windows 主机上，需要桥接网络差距——WSL2 使用虚拟网络适配器并拥有独立子网，因此 WSL2 内部的 localhost 指向的是 Linux 虚拟机，而非 Windows 主机。

两者都在 WSL2？没问题。

如果模型服务器也运行在 WSL2 中（如 vLLM、SGLang 和 llama-server 常见情况），localhost 可正常工作——它们共享同一网络命名空间。可跳过本节。

方案一：镜像网络模式（推荐）

适用于 Windows 11 22H2 及以上版本，镜像模式可实现 Windows 与 WSL2 之间的双向 localhost 通信——最简单的解决方案。

创建或编辑 %USERPROFILE%\.wslconfig（例如 C:\Users\YourName\.wslconfig）：
```
[wsl2]
networkingMode=mirrored
```
从 PowerShell 重启 WSL：
```
wsl --shutdown
```
重新打开你的 WSL2 终端。现在 localhost 可访问 Windows 服务：
```
curl http://localhost:11434/v1/models   # Ollama on Windows — works
```

Hyper-V 防火墙

在某些 Windows 11 版本中，Hyper-V 防火墙默认会阻止镜像连接。如果启用镜像模式后 localhost 仍无法使用，请在 管理员 PowerShell 中运行以下命令：

Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow

方案二：使用 Windows 主机 IP（Windows 10 / 较旧版本）

若无法使用镜像模式，请在 WSL2 中查找 Windows 主机 IP，并使用该 IP 替代 localhost：

# 获取Windows主机IP（WSL2的虚拟网络默认gateway）
ip route show | grep -i default | awk '{ print $3 }'
# 示例输出：172.29.192.1

在 OpenClaw 配置中使用该 IP：

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows 主机 IP，而不是本地主机

动态辅助工具

主机 IP 在 WSL2 重启后可能发生变化。你可以在 shell 中动态获取它：

export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }')
echo "Windows host at: $WSL_HOST"
curl http://$WSL_HOST:11434/v1/models   # 测试Ollama

或使用机器的 mDNS 名称（需在 WSL2 中安装 libnss-mdns）：

sudo apt install libnss-mdns
curl http://$(hostname).local:11434/v1/models

服务器绑定地址（NAT 模式必需）

如果你使用 方案二（NAT 模式，使用主机 IP），则运行在 Windows 上的模型服务器必须接受来自 127.0.0.1 以外的连接。默认情况下，大多数服务器仅监听 localhost——在 NAT 模式下，WSL2 的连接来自不同的虚拟子网，将被拒绝。在镜像模式下，localhost 会直接映射，因此默认的 127.0.0.1 绑定仍可正常工作。

服务器	默认绑定地址	如何修复
Ollama	`127.0.0.1`	启动 Ollama 前设置 `OLLAMA_HOST=0.0.0.0` 环境变量（Windows 系统设置 → 环境变量，或编辑 Ollama 服务）
LM Studio	`127.0.0.1`	在开发者标签页 → 服务器设置中启用 “在局域网中提供服务”
llama-server	`127.0.0.1`	在启动命令中添加 `--host 0.0.0.0`
vLLM	`0.0.0.0`	默认已绑定到所有接口
SGLang	`127.0.0.1`	在启动命令中添加 `--host 0.0.0.0`

Windows 上的 Ollama（详细说明）：Ollama 作为 Windows 服务运行。要设置 OLLAMA_HOST：

打开 系统属性 → 环境变量
添加新的 系统变量：OLLAMA_HOST = 0.0.0.0
重启 Ollama 服务（或重启系统）

Windows 防火墙

Windows 防火墙将 WSL2 视为独立网络（无论在 NAT 模式还是镜像模式下）。如果在完成上述步骤后连接仍失败，请为模型服务器的端口添加防火墙规则：

# 在管理中运行 PowerShell — 将 PORT 替换为您服务器的端口
New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434

常见端口：Ollama 11434，vLLM 8000，SGLang 30000，llama-server 8080，LM Studio 1234。

快速验证

从 WSL2 内部测试是否可以访问你的模型服务器：

# 将 URL 替换为您的服务器地址和端口
curl http://localhost:11434/v1/models          # 镜像模式
curl http://172.29.192.1:11434/v1/models       # NAT模式（使用你的实际主机IP）

如果返回包含模型列表的 JSON 响应，则说明配置正确。请将此 URL 用作 OpenClaw 配置中的 base_url。

本地模型故障排除

这些问题会影响使用 OpenClaw 时的所有本地推理服务器。

“连接被拒绝”：从 WSL2 访问运行在 Windows 主机上的模型服务器

如果你在 WSL2 中运行 OpenClaw，而模型服务器在 Windows 主机上，WSL2 默认的 NAT 网络模式下 http://localhost:<port> 将无法工作。请参阅上方的 WSL2 网络配置获取解决方案。

工具调用以文本形式出现，而非执行

模型输出类似 {"name": "web_search", "arguments": {...}} 的消息，但并未实际调用工具。

原因： 你的服务器未启用工具调用功能，或模型通过服务器的工具调用实现不支持该功能。

服务器	修复方法
llama.cpp	在启动命令中添加 `--jinja`
vLLM	添加 `--enable-auto-tool-choice --tool-call-parser hermes`
SGLang	添加 `--tool-call-parser qwen`（或相应解析器）
Ollama	工具调用默认已启用 —— 请确保你的模型支持（使用 `ollama show model-name` 检查）
LM Studio	更新至 0.3.6 或更高版本，并使用原生支持工具调用的模型

模型似乎忘记上下文或给出不连贯的响应

原因： 上下文窗口太小。当对话超过上下文限制时，大多数服务器会静默丢弃较早的消息。OpenClaw 的系统提示 + 工具模式定义本身即可占用 4k–8k 个 token。

诊断：

# 检查 OpenClaw 认为 context 是什么
# 查看启动行：“0”

# 检查您服务器的实际 context
# Ollama：ollama ps（上下文支柱）
# llama.cpp：卷曲http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM：检查启动参数中的--max-model-len

修复： 为 Agent 使用至少 32,768 个 token 的上下文。请参见上文各服务器部分，了解具体配置标志。

启动时出现 "Context limit: 2048 tokens"

OpenClaw 会自动从服务器的 /v1/models 端点检测上下文长度。如果服务器报告的值过低（或根本未报告），OpenClaw 将使用模型声明的限制，这可能是错误的。

修复： 在 config.yaml 中显式设置：

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

响应在句子中间被截断

可能原因：

服务器输出上限（max_tokens）过低 —— SGLang 默认每响应限制为 128 个 token。请在服务器上设置 --default-max-tokens，或在 config.yaml 中通过 model.max_tokens 配置 OpenClaw。注意：max_tokens 仅控制响应长度，与对话历史长度无关（后者由 context_length 控制）。
上下文耗尽 —— 模型已填满其上下文窗口。请增加 model.context_length 或在 OpenClaw 中启用上下文压缩。

LiteLLM 代理 —— 多提供商网关

LiteLLM 是一个兼容 OpenAI 的 Agent，可将 100 多个大模型提供商统一为单一 API。适用于：无需更改配置即可在不同提供商间切换、负载均衡、故障转移链、预算控制。

# 安装并启动
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000

# 或者使用多个 models 的配置文件：
litellm --config litellm_config.yaml --port 4000

然后通过 openclaw model → 自定义端点 → http://localhost:4000/v1 配置 OpenClaw。

示例 litellm_config.yaml（含故障转移）：

model_list:
  - model_name: "best"
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
  - model_name: "best"
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...
router_settings:
  routing_strategy: "latency-based-routing"

ClawRouter —— 成本优化路由

ClawRouter 由 BlockRunAI 开发，是一个本地路由 Agent，可根据查询复杂度自动选择模型。它在 14 个维度上对请求进行分类，并将任务路由至最经济的可用模型。支付方式为 USDC 加密货币（无需 API 密钥）。

# 安装并启动
npx @blockrun/clawrouter    # 在端口 8402 上启动

然后通过 openclaw model → 自定义端点 → http://localhost:8402/v1 → 模型名称 blockrun/auto 配置 OpenClaw。

路由配置文件：

配置文件	策略	节省成本
`blockrun/auto`	质量与成本的平衡	74–100%
`blockrun/eco`	尽可能便宜	95–100%
`blockrun/premium`	最佳质量模型	0%
`blockrun/free`	仅限免费模型	100%
`blockrun/agentic`	针对工具使用优化	变化

备注

ClawRouter 需要在 Base 或 Solana 网络上使用已充值 USDC 的钱包进行支付。所有请求均通过 BlockRun 的后端 API 路由。运行 npx @blockrun/clawrouter doctor 可检查钱包状态。

其他兼容提供商

任何具备 OpenAI 兼容 API 的服务均可使用。部分流行选项如下：

服务商	基础 URL	备注
Together AI	`https://api.together.xyz/v1`	云端托管开源模型
Groq	`https://api.groq.com/openai/v1`	超高速推理
DeepSeek	`https://api.deepseek.com/v1`	DeepSeek 模型
Fireworks AI	`https://api.fireworks.ai/inference/v1`	快速开源模型托管
Cerebras	`https://api.cerebras.ai/v1`	芯片级规模推理
Mistral AI	`https://api.mistral.ai/v1`	Mistral 模型
OpenAI	`https://api.openai.com/v1`	直接访问 OpenAI
Azure OpenAI	`https://YOUR.openai.azure.com/`	企业级 OpenAI
LocalAI	`http://localhost:8080/v1`	自托管，多模型支持
Jan	`http://localhost:1337/v1`	桌面应用，支持本地模型

可通过 openclaw model → 自定义端点，或在 config.yaml 中配置任意上述服务：

model:
  default: meta-llama/Llama-3.1-70B-Instruct-Turbo
  provider: custom
  base_url: https://api.together.xyz/v1
  api_key: your-together-key

上下文长度检测

两个设置，容易混淆

context_length 是 总上下文窗口 —— 输入与输出 token 的总预算（例如 Claude Opus 4.6 为 200,000）。OpenClaw 使用此值判断何时压缩历史记录，并验证 API 请求。

model.max_tokens 是输出上限——模型在单次响应中最多可生成的 token 数量。它与对话历史的长度无关。行业标准名称 max_tokens 常常引起混淆；Anthropic 的原生 API 已将其更名为 max_output_tokens 以更清晰地表达含义。

当自动检测无法正确识别窗口大小时，请设置 context_length。
仅当需要限制单次响应的长度时，才设置 model.max_tokens。

:::

OpenClaw 使用多源解析链来检测模型和提供商的正确上下文窗口：

配置覆盖 —— config.yaml 中的 model.context_length（优先级最高）
按模型自定义提供商 —— custom_providers[].models.<id>.context_length
持久化缓存 —— 之前发现的值（重启后仍保留）
端点 /models —— 查询服务器 API（本地或自定义端点）
Anthropic /v1/models —— 查询 Anthropic API 获取 max_input_tokens（仅限 API 密钥用户）
OpenRouter API —— 从 OpenRouter 实时获取模型元数据
Nous Portal —— 将 Nous 模型 ID 与 OpenRouter 元数据进行后缀匹配
models.dev —— 社区维护的注册表，包含 3800+ 模型、100+ 服务商的提供商特定上下文长度
回退默认值 —— 基于广泛模型家族模式的默认值（128K 为默认）

对于大多数设置，系统可开箱即用。该系统具备提供商感知能力——同一模型在不同服务商处可能具有不同的上下文限制（例如，claude-opus-4.6 在 Anthropic 直连时为 1M，但在 GitHub Copilot 上为 128K）。

如需显式设置上下文长度，请在模型配置中添加 context_length：

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072  # tokens

对于自定义端点，也可为每个模型设置上下文长度：

custom_providers:
  - name: "My Local LLM"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768
      deepseek-r1:70b:
        context_length: 65536

openclaw model 在配置自定义端点时会提示输入上下文长度。留空则启用自动检测。

何时手动设置

使用 Ollama 并设置了低于模型最大值的 num_ctx
希望将上下文限制在模型最大值以下（例如，在 128K 模型上设为 8K 以节省 VRAM）
运行在不暴露 /v1/models 的 Agent 之后

命名的自定义提供商

如果你使用多个自定义端点（例如本地开发服务器和远程 GPU 服务器），可以在 config.yaml 中将它们定义为命名的自定义提供商：

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key 省略 — OpenClaw 使用 "no-key-required" 作为无密钥本地服务器
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions   # 可选，从 URL 自动检测
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages  # 适用于 Anthropic 兼容代理

在会话中随时切换，使用三重语法：

/model custom:local:qwen-2.5       # 使用“0”端点和“1”-2.5
/model custom:work:llama3-70b      # 使用 llama3-70b 的“0”端点
/model custom:anthropic-proxy:claude-sonnet-4  # 使用代理

你也可以通过交互式 openclaw model 菜单选择命名的自定义提供商。

选择合适的配置方案

使用场景	推荐方案
只想让它正常工作	OpenRouter（默认）或 Nous Portal
本地模型，简单配置	Ollama
生产级 GPU 服务	vLLM 或 SGLang
Mac / 无 GPU 环境	Ollama 或 llama.cpp
多提供商路由	LiteLLM Proxy 或 OpenRouter
成本优化	ClawRouter 或 OpenRouter 配合 `sort: "price"`
最大隐私保护	Ollama、vLLM 或 llama.cpp（完全本地）
企业级 / Azure 环境	Azure OpenAI 自定义端点
中文 AI 模型	z.ai（GLM）、Kimi/Moonshot 或 MiniMax（一级支持提供商）

提示

你可以随时通过 openclaw model 切换提供商——无需重启。无论使用哪个提供商，你的对话历史、记忆和技能都会持续保留。

可选 API 密钥

功能	服务商	环境变量
网页抓取	Firecrawl	`FIRECRAWL_API_KEY`, `FIRECRAWL_API_URL`
浏览器自动化	Browserbase	`BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`
图像生成	FAL	`FAL_KEY`
高级 TTS 语音	ElevenLabs	`ELEVENLABS_API_KEY`
OpenAI TTS + 语音转录	OpenAI	`VOICE_TOOLS_OPENAI_KEY`
强化学习训练	Tinker + WandB	`TINKER_API_KEY`, `WANDB_API_KEY`
跨会话用户建模	Honcho	`HONCHO_API_KEY`
语义长期记忆	Supermemory	`SUPERMEMORY_API_KEY`

自托管 Firecrawl

默认情况下，OpenClaw 使用 Firecrawl 云 API 进行网页搜索和抓取。如果你更倾向于本地运行 Firecrawl，可以将 OpenClaw 指向自托管实例。详见 Firecrawl 的 SELF_HOST.md 获取完整设置说明。

你将获得： 无需 API 密钥，无速率限制，无按页计费，完全数据主权。

你将失去： 云版本使用 Firecrawl 的专有“Fire-engine”技术实现高级反机器人绕过（Cloudflare、CAPTCHA、IP 轮换）。自托管版本使用基础的 fetch + Playwright，因此部分受保护网站可能无法成功访问。搜索使用 DuckDuckGo 而非 Google。

设置步骤：

克隆并启动 Firecrawl Docker 堆栈（5 个容器：API、Playwright、Redis、RabbitMQ、PostgreSQL —— 需要约 4-8 GB 内存）：

git clone https://github.com/firecrawl/firecrawl
cd firecrawl
# In .env, set: USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002
docker compose up -d

将 OpenClaw 指向你的实例（无需 API 密钥）：

hermes config set FIRECRAWL_API_URL http://localhost:3002

如果你的自托管实例启用了认证，也可以设置 FIRECRAWL_API_KEY 和 FIRECRAWL_API_URL。

OpenRouter 提供商路由

使用 OpenRouter 时，你可以控制请求在各个提供者之间的路由方式。在 ~/.hermes/config.yaml 中添加一个 provider_routing 部分：

provider_routing:
  sort: "throughput"          # "price"（默认）、"throughput" 或 "latency"
  # only: ["anthropic"] # 只使用这些提供者
  # ignore: ["deepinfra"] # 跳过这些 Providers
  # order: ["anthropic", "google"] # 按此顺序尝试 Providers
  # require_parameters: true # 仅使用支持所有请求参数的 Providers
  # data_collection: "deny" # 排除可能存储 /train 数据的 Providers

快捷方式： 在任何模型名称后附加 :nitro 以按吞吐量排序（例如 anthropic/claude-sonnet-4:nitro），或附加 :floor 以按价格排序。

备用模型

配置一个备用提供者/模型，当你的主模型出现故障时（如速率限制、服务器错误、认证失败），OpenClaw 会自动切换到该备用模型：

fallback_model:
  provider: openrouter                    # 必需的
  model: anthropic/claude-sonnet-4        # 必需的
  # base_url: http://localhost:8000/v1 # 可选，用于自定义端点
  # api_key_env: MY_CUSTOM_KEY # 可选，自定义端点 API 密钥的环境变量名称

启用后，备用模型会在会话过程中自动切换，而不会丢失你的对话记录。每个会话中最多触发一次。

支持的提供者：openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba、custom。

提示

备用模型仅通过 config.yaml 配置 —— 没有对应的环境变量。有关其触发条件、支持的提供者以及与辅助任务和委托交互的完整说明，请参阅备用提供者。

智能模型路由

可选的“廉价 vs 强大”路由功能，使 OpenClaw 能够在处理复杂任务时保持使用主模型，同时将非常简短或简单的请求转发给更廉价的模型。

smart_model_routing:
  enabled: true
  max_simple_chars: 160
  max_simple_words: 28
  cheap_model:
    provider: openrouter
    model: google/gemini-2.5-flash
    # base_url: http://localhost:8000/v1 # 可选的自定义端点
    # api_key_env: MY_CUSTOM_KEY # 该端点的 API 密钥的可选环境变量名称

工作原理：

如果某次交互简短、单行且不包含代码/工具/调试类内容，OpenClaw 可能会将其路由到 cheap_model
如果该次交互看起来较复杂，OpenClaw 会继续使用主模型/提供者
如果廉价路径无法干净地处理请求，OpenClaw 会自动回退到主模型

此策略设计得较为保守，适用于快速、低风险的交互，例如：

简短的事实性问题
快速重写
轻量级摘要

它会避免将以下类型的提示进行路由：

编码/调试任务
工具密集型请求
长文本或多行分析请求

当你希望在不完全更换默认模型的前提下降低延迟或成本时，可使用此功能。

参考

配置 —— 通用配置（目录结构、配置优先级、终端后端、内存、压缩等）
环境变量 —— 所有环境变量的完整参考

推理提供商​

Anthropic（原生）​

GitHub Copilot​

一级中文 AI 服务商​

xAI (Grok) 提示缓存​

Hugging Face 推理提供者​

自定义与自托管 LLM 提供商​

通用设置​

使用 /model 切换模型​

Ollama — 本地模型，零配置​

vLLM — 高性能 GPU 推理​

SGLang — 基于 RadixAttention 的快速服务​

llama.cpp / llama-server — CPU 与 Metal 推理​

LM Studio — 带本地模型的桌面应用​

WSL2 网络配置（Windows 用户）​

方案一：镜像网络模式（推荐）​

方案二：使用 Windows 主机 IP（Windows 10 / 较旧版本）​

服务器绑定地址（NAT 模式必需）​

Windows 防火墙​

快速验证​

本地模型故障排除​

“连接被拒绝”：从 WSL2 访问运行在 Windows 主机上的模型服务器​

工具调用以文本形式出现，而非执行​

模型似乎忘记上下文或给出不连贯的响应​

启动时出现 "Context limit: 2048 tokens"​

响应在句子中间被截断​

LiteLLM 代理 —— 多提供商网关​

ClawRouter —— 成本优化路由​

其他兼容提供商​

上下文长度检测​

命名的自定义提供商​

选择合适的配置方案​

可选 API 密钥​

自托管 Firecrawl​

OpenRouter 提供商路由​

备用模型​

智能模型路由​

参考​

推理提供商

Anthropic（原生）

GitHub Copilot

一级中文 AI 服务商

xAI (Grok) 提示缓存

Hugging Face 推理提供者

自定义与自托管 LLM 提供商

通用设置

使用 `/model` 切换模型

Ollama — 本地模型，零配置

vLLM — 高性能 GPU 推理

SGLang — 基于 RadixAttention 的快速服务

llama.cpp / llama-server — CPU 与 Metal 推理

LM Studio — 带本地模型的桌面应用

WSL2 网络配置（Windows 用户）

方案一：镜像网络模式（推荐）

方案二：使用 Windows 主机 IP（Windows 10 / 较旧版本）

服务器绑定地址（NAT 模式必需）

Windows 防火墙

快速验证

本地模型故障排除

“连接被拒绝”：从 WSL2 访问运行在 Windows 主机上的模型服务器

工具调用以文本形式出现，而非执行

模型似乎忘记上下文或给出不连贯的响应

启动时出现 "Context limit: 2048 tokens"

响应在句子中间被截断

LiteLLM 代理 —— 多提供商网关

ClawRouter —— 成本优化路由

其他兼容提供商

上下文长度检测

命名的自定义提供商

选择合适的配置方案

可选 API 密钥

自托管 Firecrawl

OpenRouter 提供商路由

备用模型

智能模型路由

参考