记录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：

npm install -g openclaw

验证安装：

openclaw --version
which openclaw

首次初始化可以运行：

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 config set tools.profile "full"

openclaw gateway restart

修改配置

切换到openclaw工作空间

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

在这里插入图片描述

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

cat /Users/biao.xie/.openclaw/openclaw.json

cat /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 的核心配置如下：

{
  "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 config set agents.defaults.model.primary '"ollama-local/qwen3:4b"' --strict-json --replace
openclaw gateway restart

如需切回 DeepSeek：

openclaw config set agents.defaults.model.primary '"deepseek-api/deepseek-v4-pro"' --strict-json --replace
openclaw gateway restart

配置浏览器操作插件

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

启用插件的核心配置：

openclaw config set plugins.allow '["openclaw-lark","browser"]' --strict-json --replace
openclaw config set plugins.entries.browser '{"enabled":true}' --strict-json --merge
openclaw gateway restart

检查 browser 插件：

openclaw browser doctor

启动 OpenClaw 专用浏览器：

openclaw browser start

查看浏览器状态：

openclaw browser status

打开网页：

openclaw browser open https://example.com

查看标签页：

openclaw browser tabs

读取当前页面快照：

openclaw browser snapshot

常用浏览器命令：

openclaw browser open https://example.com
openclaw browser navigate https://example.com
openclaw browser screenshot
openclaw browser click <ref>
openclaw browser type <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 browser open https://example.com
openclaw browser snapshot

常用命令

开启和关闭

openclaw stop 

openclaw start

openclaw 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-portal OAuth 刷新失败，或旧的 Qwen portal OAuth 已不可用。

处理方式：

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

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

browser doctor 显示 gateway closed 或 connect EPERM

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

GatewayTransportError: gateway closed
connect EPERM 127.0.0.1:18789

处理方式：

  1. 在普通 macOS Terminal 中执行命令。
  2. 确认 gateway 正在运行：
openclaw gateway status
  1. 确认 browser 插件已启用：
openclaw browser doctor
  1. 如果浏览器未启动：
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 --version
openclaw gateway start
openclaw gateway restart
openclaw gateway status
openclaw logs --follow
openclaw config validate
openclaw plugins list
openclaw browser doctor
openclaw browser start
openclaw browser status
openclaw browser open https://example.com
openclaw browser tabs
openclaw browser snapshot
# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

工具调用管线断点续跑难题：状态机设计如何平衡开发与运维视角

avatar 龙虾开发者社区
cover

OpenClaw 生产可观测性实践：为什么我们最终选择分级 Trace 方案

avatar 龙虾开发者社区
cover

ClawOS 作为 Agent 宿主：不可变根文件系统下的风险隔离实践

avatar 龙虾开发者社区