OpenClaw 安装入门及基础用法

发表于 2026-07-30 分类于 AIGC 阅读次数：

OpenClaw 是一款支持多渠道接入的 AI 网关工具，可通过 Web UI、终端、各类 IM 渠道统一管理对话与 Agent 任务。本文介绍安装、配置、常用运维操作等基础用法。

一、安装

1.1 前置要求

Node.js 18+（推荐 LTS 版本）
npm 或 nvm 管理 Node 版本

1.2 通过 npm 安装

npm install -g openclaw

1.3 验证安装

openclaw --version

输出示例：OpenClaw 2026.7.1-2

1.4 初始化引导

首次安装后运行交互式引导，完成 Gateway、认证、模型、渠道等基础配置：

openclaw onboard

二、常用配置

2.1 配置文件位置

~/.openclaw/openclaw.json

2.2 查看当前配置

openclaw config get
openclaw config get gateway
openclaw config get models

2.3 修改配置（patch 方式）

推荐使用 config patch 进行合并式更新，对象递归合并、null 表示删除路径：

openclaw config patch --stdin << EOF
{
  "gateway": { "port": 18789 },
  "agents": { "defaults": { "model": "my-provider/my-model" } }
}
EOF

2.4 配置自定义 AI Provider（OpenAI 兼容）

openclaw config patch --stdin << EOF
{
  "models": {
    "providers": {
      "my-provider": {
        "baseUrl": "http://127.0.0.1:15721/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" }
        ]
      }
    }
  }
}
EOF

支持的 api 协议值：openai-completions、anthropic-messages、google-generative-ai、ollama 等。

2.5 设置默认模型

openclaw config patch --stdin << EOF
{ "agents": { "defaults": { "model": "my-provider/claude-sonnet-4-6" } } }
EOF

2.6 禁用不支持的内置工具

当后端 API 拒绝 web_fetch、web_search 等工具时，在配置中关闭：

openclaw config patch --stdin << EOF
{ "tools": { "web": { "fetch": { "enabled": false }, "search": { "enabled": false } } } }
EOF

2.7 配置 Gateway 端口

openclaw config patch --stdin << EOF
{ "gateway": { "port": 18789 } }
EOF

修改端口后需重启 Gateway 生效（见第四节）。

2.8 验证配置合法性

openclaw config validate

三、Gateway 安装与访问

3.1 安装为系统服务

openclaw gateway install

安装后 Gateway 随系统启动自动运行，日志路径：~/Library/Logs/openclaw/gateway.log

3.2 前台运行（调试用）

openclaw gateway run

3.3 查看服务状态

openclaw gateway status

3.4 访问 Web UI

Gateway 启动后，在浏览器打开：

http://127.0.0.1:18789/chat

首次访问需填写登录 Token（见第五节）。

四、启动、停止与重启

4.1 启动

openclaw gateway start

4.2 停止

openclaw gateway stop

4.3 重启

修改端口、Provider、模型等配置后，需重启 Gateway 使配置生效：

openclaw gateway restart

4.4 实时日志

openclaw logs --follow

4.5 健康检查与自动修复

openclaw doctor --fix

五、获取登录 Token

OpenClaw Web UI 使用 Token 进行本地认证，Token 在执行 openclaw gateway install 时自动生成并保存于配置文件。

5.1 方法一：直接查看配置文件（最快）

grep -i token ~/.openclaw/openclaw.json

找到 auth.token 字段的值即为登录 Token。

5.2 方法二：命令行自动打开

openclaw dashboard

自动在浏览器中打开已携带 token 的 Dashboard 页面，无需手动粘贴。

5.3 方法三：config get 查询

openclaw config get gateway.token

5.4 Token 轮换（安全更新）

# 查看已配对设备
openclaw devices list
# 轮换 token
openclaw devices rotate

六、更新 OpenClaw

6.1 查看当前版本与更新状态

openclaw update status

6.2 执行更新

openclaw update

更新完成后自动重启 Gateway。如需跳过重启：

openclaw update --no-restart

6.3 切换更新渠道

# 可选：stable（默认）| extended-stable | beta | dev
openclaw update --channel stable

6.4 预览更新（不实际执行）

openclaw update --dry-run

七、常用命令速查表

安装与初始化

npm install -g openclaw — 全局安装
openclaw onboard — 首次引导配置
openclaw configure — 交互式修改配置

Gateway 管理

openclaw gateway install — 安装为系统服务
openclaw gateway start / stop / restart — 启停重启
openclaw gateway status — 查看状态
openclaw gateway run — 前台运行（调试）

配置管理

openclaw config get [path] — 查看配置
openclaw config patch --stdin — 合并更新配置
openclaw config validate — 验证配置合法性

Token 与认证

grep -i token ~/.openclaw/openclaw.json — 查看 Token
openclaw dashboard — 打开带 token 的 Web UI
openclaw devices list / rotate — 管理设备 token

更新

openclaw update — 执行更新
openclaw update status — 查看版本与渠道
openclaw update --dry-run — 预览更新

诊断

openclaw doctor --fix — 自动修复常见问题
openclaw logs --follow — 实时查看日志
openclaw status — 查看渠道与会话状态
openclaw models status — 查看模型 / Provider 健康