OpenClaw 安装与免费千问模型配置教程

第一次接触 OpenClaw，最卡的其实不是安装，而是模型这一步：装好了、界面能开，却不知道怎么接入一个能长期用、门槛又低的模型。本文就用直接的方式，从零完成 OpenClaw 安装，并接入免费的千问（Qwen）模型。

这套方案适合个人电脑、轻量服务器和日常自用环境。按文档当前说明，Qwen 的免费层通过 OAuth 提供 Qwen Coder 和 Qwen Vision 能力，额度为每天 2,000 次请求，但仍会受到 Qwen 自身速率限制影响。

一、开始之前：需要准备什么

正式安装前，先确认环境满足以下条件：

1）Node.js 版本不低于 22。

2）能够正常访问终端并执行全局安装命令。

3）建议使用 Linux、macOS，Windows 则优先使用 WSL2。

4）如果你只是想尽快体验聊天功能，后面可以直接用 Dashboard 或 Control UI，不必一开始就配置复杂渠道。

二、安装 OpenClaw

飞书一键安装入口：https://miaoda.feishu.cn/bot?open-from=claw_official_website

官方教程：https://docs.openclaw.ai/zh-CN/install

官方推荐的安装方式是直接运行安装脚本：

bash 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash

如果你不想使用脚本，也可以使用 npm 或 pnpm 全局安装：

bash 复制代码

npm install -g openclaw@latest
pnpm add -g openclaw@latest

安装完成后，先简单确认一下命令是否可用：

bash 复制代码

openclaw --help

如果命令已经能正常输出帮助信息，说明 CLI 安装基本没有问题。

三、运行首次引导，把基础环境搭起来

对于第一次使用 OpenClaw 的用户，最省事的做法不是手改配置文件，而是直接运行官方引导向导：

bash 复制代码

openclaw onboard --install-daemon

这个向导会帮你处理几件关键事情：

1）初始化 Gateway 网关设置。

2）建立工作区。

3）配置模型与认证。

4）按需安装后台服务。

如果你暂时还不想接入 WhatsApp、Telegram、Discord 这类渠道，也没关系。先把本地控制界面和模型能力跑通，后面再加渠道更稳。

需要配置的话，在官网选择对应的教程就可以：https://docs.openclaw.ai/zh-CN/install

四、确认 Gateway 网关已经正常运行

完成引导后，先检查 Gateway 网关状态：

bash 复制代码

openclaw gateway status

如果需要前台启动，也可以手动运行：

bash 复制代码

openclaw gateway --port 18789 --verbose

默认本地控制地址一般是：

bash 复制代码

http://127.0.0.1:18789/

如果你只是想先验证 OpenClaw 是否已成功安装，可以再执行这两个检查命令：

bash 复制代码

openclaw status
openclaw health

五、启用免费的千问模型插件

OpenClaw 中免费层的千问接入方式不是直接填 API Key，而是启用 Qwen 的 OAuth 插件。先执行下面这条命令：

bash 复制代码

openclaw plugins enable qwen-portal-auth

这一步的作用，是启用 Qwen Portal 的认证能力。插件启用后，需要重启 Gateway 网关，命令如下：

bash 复制代码

openclaw gateway restart

只有重启之后，新的提供商能力才会真正被 OpenClaw 载入。

六、登录 Qwen 免费层并写入模型配置

插件启用完成后，开始进行 Qwen 登录：

bash 复制代码

openclaw models auth login --provider qwen-portal --set-default

这条命令会触发 Qwen 的设备码 OAuth 流程。你按照终端提示，在浏览器里完成登录授权即可。

登录成功后，OpenClaw 会自动写入对应的提供商配置，并把 qwen 相关能力注册进模型目录。

如果你之前已经使用过 Qwen Code CLI 登录，OpenClaw 还会尝试从 ~/.qwen/oauth_creds.json 同步凭证。不过要注意：即使已有旧凭证，也仍然建议执行一次上面的登录命令，让 qwen-portal 的 provider 条目完整创建出来。

七、把默认模型切换到免费的千问模型

Qwen Portal 当前常用的模型 ID 主要有两个：

1）qwen-portal/coder-model

2）qwen-portal/vision-model

如果你的目标是日常文本问答、代码辅助和通用助手能力，优先建议使用 coder-model：

bash 复制代码

openclaw models set qwen-portal/coder-model

设置完成后，再执行一次状态检查：

bash 复制代码

openclaw models status

如果输出里能看到 qwen-portal/coder-model 已经成为主模型，说明切换成功。

八、在聊天里临时切换模型

如果你不想改全局默认模型，也可以在某个会话中临时切换。OpenClaw 支持直接在聊天里使用 /model 命令：

bash 复制代码

/model
/model list
/model qwen-portal/coder-model
/model status

这适合你同时保留多个模型，又想在某次对话里临时体验千问。

九、如何验证配置是否真的生效

建议你按下面这个顺序验证：

第一步，检查服务是否活着：openclaw gateway status

第二步，检查模型是否已经切到 qwen-portal：openclaw models status

第三步，打开 Dashboard 或 Control UI，发一条简单测试消息，例如"你好，请介绍一下你自己"。

第四步，如果你已经接了聊天渠道，也可以直接在对应聊天界面里测试回复。

只要模型能够正常回复，说明安装和认证流程都已经打通。

十、常见问题与排查思路

插件启用了，但登录时报 provider 不存在。

通常是因为 Gateway 网关没有重启。重新执行 openclaw gateway restart，再试一次。

登录成功了，但 models status 看不到 qwen-portal。

先重新运行 openclaw models auth login --provider qwen-portal --set-default，确保 provider 条目已写入。

模型能选中，但对话不回复。

优先执行 openclaw status 和 openclaw health，看是不是 Gateway 未运行、认证失效，或其他健康检查异常。

使用过程中偶尔失败。

Qwen 免费层虽然门槛低，但仍受速率限制影响。请求高峰期出现失败、稍后重试恢复，通常属于正常现象。

十一、推荐的一套最简命令顺序

如果只想照着命令一路跑通，可以直接按这个顺序执行：

bash 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw plugins enable qwen-portal-auth
openclaw gateway restart
openclaw models auth login --provider qwen-portal --set-default
openclaw models set qwen-portal/coder-model
openclaw models status

十二、结语

OpenClaw 真正难的不是"怎么安装"，而是"装完以后如何选一个稳定、低门槛、可立即使用的模型"。免费的千问方案，正好适合作为第一步：不用先折腾复杂 API 计费，也不用上来就背一堆提供商差异。

你只需要记住一条主线：先装 OpenClaw，再启用 qwen-portal-auth，登录 Qwen，最后把默认模型切到 qwen-portal/coder-model。走通这条线，OpenClaw 基本就能真正开始用了。

除了国内便宜模型外，可以的话，配置国外模型会更好：这里有一份通过英伟达中转、做到免费调用 API 的教程：https://bugyuan.blog.csdn.net/article/details/157940867

除此之外，设置 OpenClaw 的配置文件也可以灵活使用一些第三方中转 API 或本地部署模型，在 ~/.openclaw/openclaw.json 中进行相应修改。