记录OpenClaw 安装与使用过程本文档记录 OpenClaw 安装、启动、模型配置、浏览器插件配置和常见问题处理。当前环境系统macOSOpenClaw 版本2026.5.7CLI 路径/Users/biao.xie/.npm-global/bin/openclaw主配置文件/Users/biao.xie/.openclaw/openclaw.json工作目录/Users/biao.xie/.openclaw/workspaceGateway 地址http://127.0.0.1:18789/Gateway 服务macOS LaunchAgentGateway 服务文件/Users/biao.xie/Library/LaunchAgents/ai.openclaw.gateway.plistGateway 日志/Users/biao.xie/.openclaw/logs/gateway.log当前默认模型deepseek-api/deepseek-v4-pro当前已启用插件browser openclaw-lark安装 OpenClaw如果是新机器先安装 Node.js 和 npm然后全局安装 OpenClawnpminstall-gopenclaw验证安装openclaw--versionwhichopenclaw首次初始化可以运行openclaw onboard初始化后默认配置通常位于~/.openclaw/openclaw.json启动项目OpenClaw 的主要后台服务是 gateway。启动 gatewayopenclaw gateway start重启 gatewayopenclaw 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?sessionmain运行效果对接飞书飞书配置飞书首页https://www.feishu.cn/需要配对openclaw pairing approve feishu KUXMZKLH开启权限openclaw configsettools.profilefullopenclaw gateway restart修改配置切换到openclaw工作空间cd/Users/biao.xie/.openclaw/workspacevim/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-proDeepSeek 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}}}}}}}修改模型配置后重启 gatewayopenclaw gateway restart确认日志里出现类似内容agent model: deepseek-api/deepseek-v4-pro (thinkinghigh, fastoff)可选切换到本地 Ollama 模型当前配置中已有本地 Ollama providerollama-local本地 Ollama API 地址http://127.0.0.1:11434/v1常用流程ollama serve ollama pull qwen3:4b然后把默认模型切到本地模型例如openclaw configsetagents.defaults.model.primaryollama-local/qwen3:4b--strict-json--replaceopenclaw gateway restart如需切回 DeepSeekopenclaw configsetagents.defaults.model.primarydeepseek-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 clickrefopenclaw browsertyperefhelloopenclaw browser press Enter openclaw browser closetab-idopenclaw 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?sessionmain在聊天里可以直接说打开 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停止当前在跑的 OpenClawpnpm openclaw gateway stop如果已经 pnpm link --global 过也可以直接openclaw gateway stop这会停掉由 install-daemon 安装的 gateway 服务。不再自动启动卸载后台服务如果希望「以后不要一开机/一登录就自动跑」可以卸载 daemonpnpm 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 startplugin qwen-portal-auth not found现象plugin not found: qwen-portal-auth这是旧配置残留。已从当前配置中移除plugins.entries.qwen-portal-auth plugins.allow 中的 qwen-portal-authweb_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