本地部署 OpenClaw 并接入千问（Qwen）完整指南

AI航向标

973人浏览 · 2026-04-02 15:05:04

AI航向标 · 2026-04-02 15:05:04 发布

最近千问请我喝奶茶，我想了想，还是写一篇OpenClaw接入千问的文章，来帮忙宣传下，毕竟是真金白银请我喝的奶茶。废话不多说，上干货（本文基于真实调试过程整理，不是文档复述，而是可直接跑通的实战方案）

本教程适合人群

想在本地运行 OpenClaw Gateway
希望使用阿里云千问（Qwen）而非 OpenAI
遇到「模型无回复 / Unauthorized / 配置不生效」等问题

一、环境准备

在开始之前，请确保你具备以下环境：

Node.js：v22 或更高
包管理器：推荐 pnpm
千问 API Key：

从  https://dashscope.console.aliyun.com/apiKey 获取

一般以 sk- 开头

二、安装 OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install

安装完成后，不要急着启动，关键在于配置。

三、核心配置：openclaw.json（重点）

OpenClaw 的所有核心行为，都由 openclaw.json 决定。

3.1 配置文件位置（非常关键）

推荐放在项目目录下，例如：

.openclaw-data/
  └── openclaw.json

后面启动时我们会显式指定这个目录。

3.2 千问完整配置模板

⚠️ 请务必直接填写真实 API Key，不要用环境变量占位符

{
  "meta": {
    "version": "1.0.0"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "qwen-portal/qwen-plus"
      },
      "models": {
        "qwen-portal/qwen-plus": {}
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api": "openai-completions",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "models": [
          {
            "id": "qwen-plus",
            "name": "Qwen Plus",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "token": "moltx-local-dev"
    }
  },
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  }
}

四、几个必踩的坑（提前告诉你）

1️⃣ baseUrl 配错 = 模型“空回复”

❌ 错误示例：

https://portal.qwen.ai/v1

这是 OAuth / Portal 接口，
用 API Key 调用时，模型会直接返回空内容。

✅ 正确写法：

https://dashscope.aliyuncs.com/compatible-mode/v1

2️⃣ API Key 用环境变量，很容易不生效

很多人会写成：

"apiKey": "${DASHSCOPE_API_KEY}"

如果你不是 100% 确认运行时环境变量已注入，
强烈建议直接写死 Key（至少在本地调试阶段）。

3️⃣ Gateway Token 是必须的（否则 Web UI 无法连接）

你只要在 gateway.auth.token 里写了 token：

"token": "qianwen-local-dev"

那 Web UI 必须填同一个值，否则必然：

Unauthorized: gateway token missing

五、启动 OpenClaw Gateway（推荐方式）

5.1 先清理旧进程

pkill -9 -f openclaw-gateway || true

5.2 指定配置目录启动（重点）

OPENCLAW_STATE_DIR=xxxx/openclaw/.openclaw-data \
nohup pnpm openclaw gateway run \
  --bind loopback \
  --port 18789 \
  --force \
  > gateway.log 2>&1 &

⚠️ 不指定 OPENCLAW_STATE_DIR
OpenClaw 会默认读 ~/.openclaw，你改的配置完全不会生效

5.3 验证是否启动成功

tail -n 20 gateway.log

看到以下信息基本就稳了：

listening on ws://127.0.0.1:18789
agent model: qwen-portal/qwen-plus

六、Web UI 连接方法

打开浏览器访问：
http://localhost:18789
如果显示 Disconnected / Unauthorized
点击左下角 Settings
填入 Gateway Token：

qianwen-local-dev

保存后自动重连

七、常见问题速查（FAQ）

Q1：模型不报错但不回内容？

99% 是 baseUrl 配错

Q2：一直 Unauthorized？

Web UI 没填 Gateway Token

Q3：改了配置完全没效果？

启动时没指定 OPENCLAW_STATE_DIR

八、总结

因为默认配置目录在~/.openclaw, 我用的是trae帮忙跑的，trae是用trae-sandbox环境，需要很多申请很多的权限，我索性就把配置目录设置在项目的根目录下，一切正常运行。跑起来就很舒服了，千问背后的大模型是阿里云百炼，有高额度（1000k）的免费token。
每个问题大概消耗12k 的token，如下图