在 OpenClaw 中使用千问AI平台模型
OpenClaw(昵称"龙虾")是一个开源的个人 AI 助手平台,支持通过多种消息渠道与 AI 交互。
OpenClaw 需要 Node.js 24.16+ 或 26.1+。可通过以下命令检查 Node.js 版本:
如果未安装或版本不符合要求,请访问 Node.js 官网下载安装。
首次安装后,OpenClaw 会自动启动引导式配置。2026.7.1 及以上可执行
首次配置:复制以下内容到配置文件,将
输出中应该包含
在
以上配置中
在 Channels 部分,DingTalk 应显示为
根据界面交互提示,完成以下配置。
在 Channels 部分,Feishu 应显示为
输出中应包含
输出中应该包含
以上配置中
通过邮箱渠道,您可以使用 163 邮箱等支持 IMAP/SMTP 协议的邮箱与 OpenClaw 进行交互。
输出中应包含
在
在 Channels 部分,Email 应显示为
配置过程中遇到报错,参考对应计费方案的常见问题文档:
使用 qwen4-max-preview 时,可用
params.cacheRetention 设置 short、long 或 none,long 对应 1 小时 TTL。使用 qwen4-max 时,可用
params.cacheRetention 设置 short、long 或 none,long 对应 1 小时 TTL。qwen4-max 的上下文长度为 1M Token;非思考模式最大输出 131,072 Token,思考与最终回答合计最大 262,144 Token;默认 reasoning_effort=high,thinking_budget=131072。安装 OpenClaw
OpenClaw 需要 Node.js 24.16+ 或 26.1+。可通过以下命令检查 Node.js 版本:
- macOS / Linux
- Windows
推荐使用官方安装脚本:或通过 npm 全局安装:
openclaw onboard(引导式)或 openclaw onboard --classic(经典向导);2026.6.35 及以下直接执行 openclaw onboard(即经典向导)。
快速开始
1
安装 Qwen 插件
无法安装插件时,参考通过配置文件接入。
2
获取 API Key
- Token Plan
- 按量计费
按 Token Plan 版本获取 API Key:
- Token Plan 个人版:创建或查看 API Key
- Token Plan 团队版:分配坐席并获取 API Key
3
配置模型
按计费方案运行对应命令,并按提示输入 API Key。
- Token Plan
- 按量计费
4
验证
运行以下命令确认模型列表和调用结果:
通过配置文件接入
Token Plan 个人版
配置文件位于
~/.openclaw/openclaw.json,OpenClaw 启动时会自动读取。
示例禁用了网关鉴权(
auth.mode: none),仅适合单机本地使用。如需共享或远程访问,请运行 openclaw doctor --generate-gateway-token 生成 token,再重启 Gateway。YOUR_API_KEY 替换为 Token Plan 个人版 API Key。
已有配置:若需保留已有配置,请勿直接全量替换,详见已有配置如何安全修改。
Token Plan 团队版
配置文件位于
~/.openclaw/openclaw.json,OpenClaw 启动时会自动读取。
示例禁用了网关鉴权(
auth.mode: none),仅适合单机本地使用。如需共享或远程访问,请运行 openclaw doctor --generate-gateway-token 生成 token,再重启 Gateway。- 方式一:终端方式
- 方式二:Web UI 方式
- 打开配置文件
-
写入配置
首次配置:复制以下内容到配置文件,将
YOUR_API_KEY替换为 Token Plan 团队版 API Key。 已有配置:若需保留已有配置,请勿直接全量替换,详见已有配置如何安全修改。
-
保存并退出
按
Ctrl+X,按Y确认保存,按Enter确认文件名。 - 使配置生效 运行以下命令重启网关,使配置生效。
按量计费
配置文件位于
~/.openclaw/openclaw.json,OpenClaw 启动时会自动读取。
示例禁用了网关鉴权(
auth.mode: none),仅适合单机本地使用。如需共享或远程访问,请运行 openclaw doctor --generate-gateway-token 生成 token,再重启 Gateway。- 方式一:终端方式
- 方式二:Web UI 方式
- 打开配置文件
-
写入配置
首次配置:复制以下内容到配置文件,将
YOUR_API_KEY替换为千问AI平台 API Key。 已有配置:若需保留已有配置,请勿直接全量替换,详见已有配置如何安全修改。
-
保存并退出
按
Ctrl+X,按Y确认保存,按Enter确认文件名。 - 使配置生效 运行以下命令重启网关,使配置生效。
接入消息渠道
钉钉
步骤一:创建钉钉应用并获取凭证
- 选择或创建组织
-
创建钉钉机器人应用
- 登录钉钉开放平台,在顶部菜单栏,选择应用。
- 在页面右侧,单击创建应用,填写应用名称(例如"AI 助手")和描述,然后单击保存,系统自动进入应用详情页。
- 在应用详情的添加应用能力页面,选择添加机器人。
-
配置机器人:
- 开启机器人配置开关。
- 填写机器人名称等必填项。
- 消息接收模式 采用默认的 Stream 模式。
- 单击发布。
- 获取应用凭证 在左侧导航栏,单击凭证与基础信息,获取Client ID和Client Secret。后续部署时使用。
-
发布应用
- 在应用详情的左侧导航栏,单击版本管理与发布。
- 在页面右侧,单击创建新版本,填写版本号(例如 1.0.0)。
- 设置可见范围,例如仅我可见。
- 单击保存,然后确认发布。
步骤二:安装钉钉渠道插件
- 在终端执行以下命令安装钉钉渠道插件
- 安装完成后,执行以下命令确认插件已加载:
dingtalk插件且状态为 loaded。
步骤三:配置钉钉渠道
在 ~/.openclaw/openclaw.json 中添加 channels 和 plugins.allow 配置。将 YOUR_DINGTALK_APPKEY 和 YOUR_DINGTALK_APPSECRET 替换为步骤一中获取的凭证。请将 channels 和 plugins 添加到已有配置文件的对应位置,不要覆盖已有的 models、agents 等配置。
如果使用轻量应用服务器或无影云电脑部署 OpenClaw,通常可以通过图形化界面进行配置,无需手动修改配置文件,具体请参见对应产品的文档。
dmPolicy 和 groupPolicy 均设为 open,适用于测试或个人使用场景。生产环境中建议设为 allowlist,通过白名单限制可访问的用户和群组,降低安全风险。
切换到 allowlist 模式时,将 dmPolicy 和 groupPolicy 改为 "allowlist",并添加 allowFrom 字段,填入允许访问的工号和群 ID。示例:
步骤四:测试
- 执行以下命令重启网关。
- 执行以下命令检查钉钉渠道状态
ON 且状态为 OK - configured。
3. 在钉钉群聊中找到机器人,发送消息进行测试。
飞书
步骤一:创建飞书应用
- 访问飞书开放平台,单击创建企业自建应用,填写应用名称和描述,选择应用图标,单击创建。
- 左侧导航栏单击凭证与基础信息 页面,复制App ID(格式如
cli_xxx)和App Secret。 - 左侧导航栏单击 权限管理页面,单击批量导入/导出权限 按钮,粘贴以下 JSON 配置,单击下一步,确认新增权限,单击申请开通。
JSON配置文件内容
JSON配置文件内容
- 左侧导航栏中单击添加应用能力, 选择按能力添加页签,找到机器人卡片,单击配置。
-
配置事件订阅。
- 在飞书开放平台左侧导航栏单击事件与回调,在事件配置页签中单击订阅方式,选择使用 长连接 接收事件,单击保存。
- 在事件配置页面,单击添加事件,搜索事件
im.message.receive_v1(接收消息),单击确认添加。
- 在 版本管理与发布 页面创建版本,填写应用版本号和更新说明,单击保存,提交审核并发布。
步骤二:配置飞书机器人
- 在终端中输入以下命令配置飞书渠道
- 选择 Feishu
- 输入 App ID
- 输入 App Secret
步骤三:测试
- 执行以下命令重启网关。
- 执行以下命令检查飞书渠道状态
ON 且状态为 OK。 3. 在飞书中发送消息进行测试。
微信
请确保微信版本不低于 8.0.70。
步骤一:安装微信渠道插件
- 在终端中执行以下命令安装微信渠道插件。
- 安装完成后,终端会显示一个二维码,使用微信扫描该二维码完成身份绑定。绑定成功后,微信会自动弹出 ClawBot 的聊天页面。
- 安装完成后,执行以下命令确认插件已加载:
openclaw-weixin 插件且状态为 loaded。
步骤二:测试
- 执行以下命令重启网关。
- 在微信中找到 ClawBot,发送消息进行测试。
QQ
步骤一:安装 QQ 渠道插件
- 在终端中执行以下命令安装 QQ 渠道插件:
- 安装完成后,执行以下命令确认插件已加载:
qqbot插件且状态为loaded 。
步骤二:创建 QQ 机器人
- 访问QQ 开放平台,注册并登录开发者账号。
-
在OpenClaw 专属页面创建机器人,并获取 AppID 和 AppSecret。
AppSecret 不支持明文保存,二次查看将会强制重置,请自行妥善保存。
- 创建完毕后,QQ 会自动弹出机器人聊天页面。
步骤三:接入 QQ 消息渠道
- 在
~/.openclaw/openclaw.json中添加channels和plugins.allow配置。将YOUR_APP_ID和YOUR_APP_SECRET替换为步骤二中获取的凭证。请将channels和plugins添加到已有配置文件的对应位置,不要覆盖已有的models、agents等配置。
dmPolicy设为open表示允许私聊,allowFrom设为["*"]表示允许所有用户消息,适用于测试或个人使用场景,生产环境中建议根据实际需求限制访问范围。 2. 配置完成后重启网关。
- 在 QQ 中向机器人发送消息进行测试。
邮箱
通过邮箱渠道,您可以使用 163 邮箱等支持 IMAP/SMTP 协议的邮箱与 OpenClaw 进行交互。
步骤一:安装邮箱渠道插件
- 在终端中执行以下命令安装邮箱渠道插件:
- 安装完成后,执行以下命令确认插件已加载:
email 插件且状态为 loaded。
步骤二:配置邮箱渠道
在 ~/.openclaw/openclaw.json 中添加 channels 和 plugins.allow 配置。请将 channels 和 plugins 添加到已有配置文件的对应位置,不要覆盖已有的 models、agents 等配置。
以 163 邮箱为例,将 YOUR_EMAIL 替换为您的 163 邮箱地址,将 YOUR_AUTH_CODE 替换为 163 邮箱的授权码(非登录密码,需在 163 邮箱设置中开启 IMAP 服务后获取)。
步骤三:测试
- 执行以下命令重启网关。
- 执行以下命令检查邮箱渠道状态。
ON 且状态为 OK。
3. 向配置的邮箱地址发送一封邮件,验证机器人是否自动回复。
错误码
配置过程中遇到报错,参考对应计费方案的常见问题文档:
- Token Plan:Token Plan 常见问题
- 按量计费:错误码
常见问题
如何查看已配置的模型?
如何查看已配置的模型?
在终端输入
openclaw tui,进入 OpenClaw 终端命令行,接着输入/model查看模型列表。按回车键选中模型,按Esc键退出模型列表。为什么报错"HTTP 401: Incorrect API key provided."、"No API key found for provider xxx"或"HTTP 401: invalid_iam_token"?
为什么报错"HTTP 401: Incorrect API key provided."、"No API key found for provider xxx"或"HTTP 401: invalid_iam_token"?
可能原因:
- API Key 无效、过期、为空、格式错误,或与端点环境不匹配。请检查 API Key 是否与所使用的付费方式匹配,并确保复制完整且无空格;确认订阅状态有效。
- OpenClaw 的历史配置缓存导致配置错误,请删除
~/.openclaw/agents/main/agent/models.json文件中的providers配置项,并重启 OpenClaw。 invalid_iam_token表示 API Key 鉴权校验失败。常见场景:API Key 已被吊销或禁用、API Key 与 Base URL 不匹配、使用临时凭证且已过期。请核对 API Key 与 Base URL 是否匹配,并确认 API Key 状态正常。
我已经配置过钉钉等其他渠道,如何安全地添加新套餐模型(防止原有配置丢失)?
我已经配置过钉钉等其他渠道,如何安全地添加新套餐模型(防止原有配置丢失)?
- 请勿直接全量覆盖。直接"全部替换"会覆盖掉自定义配置,请进行局部修改。
-
可以选择以下方式完成配置:
- 若 OpenClaw 可正常对话:直接在 OpenClaw 对话中输入指令完成配置合并。
- 若 OpenClaw 未配置模型或无法对话:请手动编辑
~/.openclaw/openclaw.json,只修改需要变更的字段,保留原有配置不变。
报错 device identity required 怎么办?
报错 device identity required 怎么办?
详细报错信息:原因:客户端连接网关时未提供设备身份信息,通常由以下原因导致:如果仍未解决,先清除异常的设备记录再重试:执行
- 首次打开浏览器访问地址,尚未完成设备配对。
- 浏览器缓存被清除,设备密钥丢失。
- 重装或升级 OpenClaw 后,
~/.openclaw/identity/目录下的密钥文件缺失。
openclaw devices list,确认设备显示在 Paired 列表中即为正常。没有主动使用 OpenClaw,但仍产生了 Token 消耗
没有主动使用 OpenClaw,但仍产生了 Token 消耗
**原因:**OpenClaw 内置心跳机制(Heartbeat),网关运行期间会按固定间隔(默认 30 分钟)自动调用已配置的模型,检查是否有待处理任务。每次心跳都会消耗少量 Token。**如何确认:**查看
~/.openclaw/agents/main/sessions/ 目录下的会话记录文件(.jsonl),其中包含 [OpenClaw heartbeat poll] 标记的心跳调用记录。解决方法:- 停止网关:不使用时执行
openclaw gateway stop,心跳随即停止。 - 增大心跳间隔:在
~/.openclaw/openclaw.json中设置agents.defaults.heartbeat.every,例如"2h"表示每 2 小时一次。