当前位置：首页 > news >正文

记录OpenClaw 安装与使用过程

news 2026/5/10 11:11:35

记录OpenClaw 安装与使用过程

本文档记录 OpenClaw 安装、启动、模型配置、浏览器插件配置和常见问题处理。

当前环境

系统：macOS
OpenClaw 版本：2026.5.7
CLI 路径：/Users/biao.xie/.npm-global/bin/openclaw
主配置文件：/Users/biao.xie/.openclaw/openclaw.json
工作目录：/Users/biao.xie/.openclaw/workspace
Gateway 地址：http://127.0.0.1:18789/
Gateway 服务：macOS LaunchAgent
Gateway 服务文件：/Users/biao.xie/Library/LaunchAgents/ai.openclaw.gateway.plist
Gateway 日志：/Users/biao.xie/.openclaw/logs/gateway.log

当前默认模型：

deepseek-api/deepseek-v4-pro

当前已启用插件：

browser openclaw-lark

安装 OpenClaw

如果是新机器，先安装 Node.js 和 npm，然后全局安装 OpenClaw：

npminstall-gopenclaw

验证安装：

openclaw--versionwhichopenclaw

首次初始化可以运行：

openclaw onboard

初始化后，默认配置通常位于：

~/.openclaw/openclaw.json

启动项目

OpenClaw 的主要后台服务是 gateway。

启动 gateway：

openclaw gateway start

重启 gateway：

openclaw gateway restart

查看状态：

openclaw gateway status

查看日志：

openclaw logs--follow

或直接查看日志文件：

tail-f/Users/biao.xie/.openclaw/logs/gateway.log

浏览器访问控制台：

http://127.0.0.1:18789/

如果要进入已有会话：

http://127.0.0.1:18789/chat?session=main

运行效果

对接飞书

飞书配置
飞书首页：https://www.feishu.cn/
需要配对

openclaw pairing approve feishu KUXMZKLH

开启权限

openclaw configsettools.profile"full"

openclaw gateway restart

修改配置

切换到openclaw工作空间

cd/Users/biao.xie/.openclaw/workspace

vim/Users/biao.xie/.openclaw/openclaw.jsoncat/Users/biao.xie/.openclaw/openclaw.jsoncat/Users/biao.xie/.openclaw/openclaw.json

修改openclaw.json配置

{"meta":{"lastTouchedVersion":"2026.3.8","lastTouchedAt":"2026-03-11T02:44:50.276Z"},"wizard":{"lastRunAt":"2026-03-11T02:44:50.254Z","lastRunVersion":"2026.3.8","lastRunCommand":"onboard","lastRunMode":"local"},"models":{"mode":"merge","providers":{"custom-127-0-0-1-11434":{"baseUrl":"http://127.0.0.1:11434/v1","apiKey":"123","api":"openai-completions","models":[{"id":"qwen3:4b","name":"qwen3:4b (Custom Provider)","api":"openai-completions","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":16000,"maxTokens":4096},{"id":"qwen3.5:4b","name":"qwen3.5:4b (Custom Provider)","api":"openai-completions","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":16000,"maxTokens":4096},{"id":"deepseek-r1:1.5b","name":"deepseek-r1:1.5b (Custom Provider)","api":"openai-completions","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":16000,"maxTokens":4096},{"id":"qwen3.5:2b","name":"qwen3.5:2b (Custom Provider)","api":"openai-completions","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":16000,"maxTokens":4096},{"id":"qwen3.5:9b","name":"qwen3.5:9b (Custom Provider)","reasoning":false,"input":["text"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":16000,"maxTokens":4096}]}}},"agents":{"defaults":{"model":{"primary":"custom-127-0-0-1-11434/qwen3.5:9b"},"models":{"ollama/qwen3:4b":{},"custom-127-0-0-1-11434/qwen3:4b":{},"custom-127-0-0-1-11434/qwen3.5:4b":{},"custom-127-0-0-1-11434/deepseek-r1:1.5b":{},"ollama/qwen3.5:2b":{},"custom-127-0-0-1-11434/qwen3.5:2b":{},"custom-127-0-0-1-11434/qwen3.5:9b":{"alias":"ollama"}},"workspace":"/Users/biao.xie/.openclaw/workspace"}},"tools":{"profile":"full","web":{"search":{"enabled":true,"provider":"brave","apiKey":"1"}}},"commands":{"native":"auto","nativeSkills":"auto","restart":true,"ownerDisplay":"raw"},"session":{"dmScope":"per-channel-peer"},"hooks":{"internal":{"enabled":true,"entries":{"boot-md":{"enabled":true},"bootstrap-extra-files":{"enabled":true},"command-logger":{"enabled":true},"session-memory":{"enabled":true}}}},"channels":{"feishu":{"enabled":true,"appId":"","appSecret":"","connectionMode":"websocket","domain":"feishu","groupPolicy":"open"}},"gateway":{"port":18789,"mode":"local","bind":"loopback","auth":{"mode":"token","token":""},"tailscale":{"mode":"off","resetOnExit":false},"nodes":{"denyCommands":["camera.snap","camera.clip","screen.record","contacts.add","calendar.add","reminders.add","sms.send"]}},"skills":{"install":{"nodeManager":"npm"},"entries":{"goplaces":{"apiKey":"1"},"nano-banana-pro":{"apiKey":"1"}}},"plugins":{"load":{"paths":["/Users/biao.xie/java/github/openclaw/extensions/feishu"]},"entries":{"feishu":{"enabled":true}}}}

飞书运行效果

配置默认模型为 DeepSeek

当前已经把默认模型切到：

deepseek-api/deepseek-v4-pro

DeepSeek provider 的核心配置如下，注意不要把真实 API Key 写入文档、仓库或聊天记录：

{"models":{"providers":{"deepseek-api":{"baseUrl":"https://api.deepseek.com","apiKey":"YOUR_DEEPSEEK_API_KEY","api":"openai-completions","models":[{"id":"deepseek-v4-pro","name":"DeepSeek V4 Pro","api":"openai-completions","reasoning":true,"input":["text"],"contextWindow":128000,"maxTokens":8192}]}}},"agents":{"defaults":{"model":{"primary":"deepseek-api/deepseek-v4-pro"},"thinkingDefault":"high","models":{"deepseek-api/deepseek-v4-pro":{"params":{"extra_body":{"thinking":{"type":"enabled"},"reasoning_effort":"high"}}}}}}}

修改模型配置后重启 gateway：

openclaw gateway restart

确认日志里出现类似内容：

agent model: deepseek-api/deepseek-v4-pro (thinking=high, fast=off)

可选：切换到本地 Ollama 模型

当前配置中已有本地 Ollama provider：

ollama-local

本地 Ollama API 地址：

http://127.0.0.1:11434/v1

常用流程：

ollama serve ollama pull qwen3:4b

然后把默认模型切到本地模型，例如：

openclaw configsetagents.defaults.model.primary'"ollama-local/qwen3:4b"'--strict-json--replaceopenclaw gateway restart

如需切回 DeepSeek：

openclaw configsetagents.defaults.model.primary'"deepseek-api/deepseek-v4-pro"'--strict-json--replaceopenclaw gateway restart

配置浏览器操作插件

当前已经启用browser插件。它用于让 OpenClaw 打开网页、读取页面内容、点击、输入、截图和操作标签页。

启用插件的核心配置：

openclaw configsetplugins.allow'["openclaw-lark","browser"]'--strict-json--replaceopenclaw configsetplugins.entries.browser'{"enabled":true}'--strict-json--mergeopenclaw gateway restart

检查 browser 插件：

openclaw browser doctor

启动 OpenClaw 专用浏览器：

openclaw browser start

查看浏览器状态：

openclaw browser status

打开网页：

openclaw browseropenhttps://example.com

查看标签页：

openclaw browser tabs

读取当前页面快照：

openclaw browser snapshot

常用浏览器命令：

openclaw browseropenhttps://example.com openclaw browser navigate https://example.com openclaw browser screenshot openclaw browser click<ref>openclaw browsertype<ref>"hello"openclaw browser press Enter openclaw browser close<tab-id>openclaw browser stop

当前验证结果：

browser plugin: enabled profile: openclaw running: true transport: cdp browser: chrome test url: https://example.com/

日常使用方式

启动服务：

openclaw gateway start

打开 Web 控制台：

http://127.0.0.1:18789/

打开 main 会话：

http://127.0.0.1:18789/chat?session=main

在聊天里可以直接说：

打开 https://example.com 并总结页面内容 在当前网页点击 Learn more 打开浏览器搜索 OpenClaw browser plugin

如果要从命令行直接操作浏览器：

openclaw browser start openclaw browseropenhttps://example.com openclaw browser snapshot

常用命令

开启和关闭

openclaw stop openclawstartopenclaw gateway restart openclaw status--all

首次可跑一次引导

pnpm openclaw onboard--install-daemon

看 gateway 是否在跑

pnpm openclaw gateway status

打开网页控制台

pnpm openclaw dashboard

停止当前在跑的 OpenClaw

pnpm openclaw gateway stop

如果已经 pnpm link --global 过，也可以直接：

openclaw gateway stop

这会停掉由 install-daemon 安装的 gateway 服务。

不再自动启动（卸载后台服务）

如果希望「以后不要一开机/一登录就自动跑」，可以卸载 daemon：

pnpm openclaw gateway uninstall

之后 gateway 就不会被系统自动拉起；想再要后台常驻时再执行：

pnpm openclaw gateway install

自定义模型

Model/auth provider
│ Custom Provider
│
◆ API Base URL
│ http://127.0.0.1:11434/v1

运行效果

参考文档

OpenClaw飞书官方插件上线｜一文讲清功能、安装更新教程与常见问题！

OpenClaw飞书官方插件使用指南（公开版）

常见问题

Qwen OAuth 504 或 token refresh failed

现象：

Agent failed before reply: OAuth token refresh failed for qwen-portal Qwen OAuth refresh failed: 504 Gateway Time-out

原因通常是qwen-portalOAuth 刷新失败，或旧的 Qwen portal OAuth 已不可用。

处理方式：

使用当前已配置的 DeepSeek 默认模型。
如果必须继续使用 Qwen，重新执行 Qwen API Key 方式的登录或迁移。

当前默认模型已经切到 DeepSeek，因此正常聊天不再依赖qwen-portal。

browser doctor 显示 gateway closed 或 connect EPERM

在受限沙盒里运行 CLI 时，可能会看到：

GatewayTransportError: gateway closed connect EPERM 127.0.0.1:18789

处理方式：

在普通 macOS Terminal 中执行命令。
确认 gateway 正在运行：

openclaw gateway status

确认 browser 插件已启用：

openclaw browser doctor

如果浏览器未启动：

openclaw browser start

plugin qwen-portal-auth not found

现象：

plugin not found: qwen-portal-auth

这是旧配置残留。已从当前配置中移除：

plugins.entries.qwen-portal-auth plugins.allow 中的 qwen-portal-auth

web_search provider brave 不可用

现象：

tools.web.search.provider: web_search provider is not available: brave

这不影响 gateway、模型或 browser 插件。需要 Web 搜索时再安装或启用 Brave provider，或者把 web search provider 改成已安装的搜索插件。

openclaw-lark channelConfigs warning

现象：

plugin openclaw-lark: channel plugin manifest declares feishu without channelConfigs metadata

这是openclaw-lark插件 manifest 的元数据警告，不影响当前 browser 插件和 DeepSeek 模型使用。要彻底修复，需要在插件的openclaw.plugin.json中补充channelConfigs元数据。

安全注意事项

不要把openclaw.json上传到公开仓库。
不要在文档中写入真实 API Key、gateway token、Feishu app secret。
当前文档中的YOUR_DEEPSEEK_API_KEY是占位符。
修改认证信息后，建议执行：

openclaw gateway restart

快速命令清单

openclaw--versionopenclaw gateway start openclaw gateway restart openclaw gateway status openclaw logs--followopenclaw config validate openclaw plugins list openclaw browser doctor openclaw browser start openclaw browser status openclaw browseropenhttps://example.com openclaw browser tabs openclaw browser snapshot

查看全文

http://www.jsqmd.com/news/780131/