OpenClaw 安装与初始化记录

发表于 | 分类于

OpenClaw 安装与初始化记录

日期: 2026-03-30
操作人: imwl
主机环境: Linux (aarch64/arm64), OrbStack VM
OpenClaw 版本: 2026.3.28 (f9b1079)

1. 环境准备

1.1 检查系统环境

项目 值
操作系统 Linux (linux-gnu)
架构 aarch64 (arm64)
Shell bash
curl 8.14.1
Node.js v24.14.1 (通过 NVM 安装)
npm 11.11.0
Node.js 路径 /home/imwl/.nvm/versions/node/v24.14.1/bin/node

1.2 下载安装脚本

1
curl -fsSL https://openclaw.ai/install.sh -o /tmp/openclaw_install.sh

审查脚本后确认安全（标准 Node.js CLI 工具安装程序，约 2637 行 bash 脚本）。

2. 执行安装

2.1 安装命令

1
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard --no-prompt --verbose

参数说明：

  • --no-onboard: 跳过交互式引导（非交互式终端必需）
  • --no-prompt: 禁用所有交互提示
  • --verbose: 显示详细输出（set -x）

2.2 安装过程

安装脚本分 3 个阶段执行：

阶段 1/3: Preparing environment（准备环境）

  1. 检测操作系统: 识别为 Linux
  2. 选择安装方式: 自动选择 npm（未检测到 git 源码仓库）
  3. 检查 Node.js: Node.js v24.14.1 已存在且版本 >= 22，满足要求
  4. 安装 Git: Git 未找到，通过 apt-get 自动安装
    • sudo apt-get update -qq
    • sudo apt-get install -y -qq git
    • 安装了 git 1:2.51.0-1ubuntu1 及其依赖（perl, liberror-perl 等）

阶段 2/3: Installing OpenClaw（安装 OpenClaw）

  1. 解析版本: 通过 npm view openclaw@latest version 确认最新版本为 2026.3.28

  2. npm 全局安装:

    1
    env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm --loglevel notice --no-fund --no-audit install -g openclaw@latest

  3. 安装结果: 成功安装 478 个包，耗时约 40 秒

  4. npm 警告: `[email protected]` 已弃用（不影响功能）

阶段 3/3: Finalizing setup（完成设置）

  1. 二进制路径解析: /home/imwl/.nvm/versions/node/v24.14.1/bin/openclaw
  2. Gateway 状态检查: systemd 服务未加载（正常，首次安装）
  3. 跳过 onboarding: 因 --no-onboard 参数
  4. 安装完成: 确认版本 OpenClaw 2026.3.28 (f9b1079)

3. 安装验证

3.1 二进制位置与版本

1
2
3
4
5
$ which openclaw
/home/imwl/.nvm/versions/node/v24.14.1/bin/openclaw

$ openclaw --version
OpenClaw 2026.3.28 (f9b1079)

3.2 主要命令

OpenClaw 提供以下主要命令组：

命令 说明
gateway 运行/管理 WebSocket Gateway
doctor 健康检查与修复
configure 交互式配置向导
channels 管理聊天渠道（Telegram, Discord 等）
agents 管理独立 agent
plugins 插件管理
config 非交互式配置
backup 备份管理
devices 设备配对与令牌管理
logs 查看 Gateway 日志
dashboard 打开 Web 控制面板
cron 定时任务管理
docs 搜索文档

4. 初始化配置

4.1 运行 Doctor 检查

1
openclaw doctor --non-interactive

Doctor 检查结果摘要：

检查项 状态 说明
Startup optimization 建议 建议设置 NODE_COMPILE_CACHE 和 OPENCLAW_NO_RESPAWN
Gateway 警告 gateway.mode 未设置
Gateway auth 警告 建议启用 token 认证
State integrity 严重 ~/.openclaw 目录缺失
Security 正常 无安全警告
Skills 信息 5 个可用，45 个缺少依赖
Plugins 正常 41 个已加载，41 个已禁用，0 个错误
Gateway 信息 未运行
Memory search 警告 无 embedding provider 可用
Gateway service 信息 服务未安装

4.2 配置 Gateway 模式

1
openclaw config set gateway.mode local

输出: Updated gateway.mode. Restart the gateway to apply.

4.3 Gateway 状态

1
openclaw gateway status

关键信息：

  • 绑定模式: loopback (127.0.0.1)
  • 端口: 18789
  • Dashboard: http://127.0.0.1:18789/
  • 运行时状态: stopped (inactive)
  • 日志路径: /tmp/openclaw/openclaw-2026-03-30.log

4.4 插件列表

1
openclaw plugins list
  • 总计 82 个插件，其中 41 个已加载
  • 已加载的关键插件: Amazon Bedrock, Anthropic, Browser 等
  • 来源: stock (内置)

5. 安装的文件与路径

路径 说明
/home/imwl/.nvm/versions/node/v24.14.1/bin/openclaw 可执行文件
/home/imwl/.nvm/versions/node/v24.14.1/lib/node_modules/openclaw/ npm 包目录
~/.openclaw/ 配置与状态目录（需完成 onboarding）
~/.openclaw/openclaw.json 主配置文件
/tmp/openclaw/ 运行时日志目录

6. 安装 Gateway 系统服务

6.1 安装服务

1
openclaw gateway install

执行结果：

  • 自动检测到配置文件变更，创建了备份 ~/.openclaw/openclaw.json.bak
  • 未找到 gateway token，自动生成并保存到配置
  • 安装了 systemd 用户服务: ~/.config/systemd/user/openclaw-gateway.service

6.2 启动 Gateway

1
openclaw gateway start

输出: Restarted systemd service: openclaw-gateway.service

6.3 验证 Gateway 状态

1
openclaw gateway status
项目 值
Service systemd (enabled)
Runtime running (pid 19903)
RPC probe ok
Bind 127.0.0.1:18789
Dashboard http://127.0.0.1:18789/
日志 /tmp/openclaw/openclaw-2026-03-30.log

使用 ssh 隧道访问

ssh -N -L 18789:127.0.0.1:18789 user@host 后访问 dashboard

6.4 健康检查

1
openclaw health
  • Agents: main (default)
  • Heartbeat interval: 30m
  • Session store: 0 entries

6.5 注意事项

  • 服务 PATH 包含 NVM 版本管理器路径，Node.js 升级后可能需要重新安装服务
  • 建议安装系统级 Node.js 22 LTS 以避免版本管理器带来的潜在问题
  • 可运行 openclaw doctor --fix 修复检测到的问题

7. 成本控制

1
2
3
4
5
6
7
8
# 设置月度预算（美元）
openclaw config set budget.monthly 50

# 设置单日预算
openclaw config set budget.daily 5

# 查看本月使用情况
openclaw gateway usage-cost

7.1 成本控制技巧

  1. 选择合适的模型

    • 简单任务用轻量模型（zai/glm-4.7-flash）
    • 复杂任务才用强模型（moonshot/kimi-k2.5）

  2. 限制上下文长度

    1
    2
    3
    4
    5
    6
    7
    {
      "models": {
        "primary": {
          "maxTokens": 4000
        }
      }
    }

  3. 设置调用频率限制

    1
    2
    3
    4
    5
    6
    {
      "rateLimit": {
        "perMinute": 30,
        "perHour": 500
      }
    }

模型配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "models": {
    "primary": {
      "provider": "kimi",
      "model": "kimi-k2.5",
      "apiKey": "sk-xxx"
    },
    "fallbacks": [
      {
        "provider": "minimax",
        "model": "MiniMax-M2.5",
        "apiKey": "xxx"
      },
      {
        "provider": "glm",
        "model": "glm-5",
        "apiKey": "xxx"
      }
    ]
  }
}

  1. 优先使用primary模型

  2. 如果primary失败（如额度用完、服务异常），自动切换到fallbacks[0]

  3. 如果fallbacks[0]也失败，切换到fallbacks[1]

  4. 以此类推

    8. 后续步骤

  5. 完成初始化引导:

    1
    openclaw onboard

    （需要在交互式终端中运行）

  6. 配置 AI 提供商 (至少配置一个):

    1
    openclaw configure --section model

  7. 配置 IM (飞书为例):

    1
    2
    3
    4
    openclaw plugins list
    openclaw plugins enable feishu
    openclaw channels add
    openclaw channels list

  8. 运行修复:

    1
    openclaw doctor --fix

9 补充

1. device identity required

步骤1：查看待批准设备

1
openclaw devices list

步骤2：批准设备

1
2
3
4
5
# 批准特定设备
openclaw devices approve <设备ID>

# 或批准所有待批准设备
openclaw devices approve --all

2. skills 加载目录

1
2
3
4
5
6
<workspace>/skills          ← workspace 级别，最高                                                                                                                                         
  <workspace>/.agents/skills  ← 项目 agent 级别                                                                                                                                              
  ~/.agents/skills            ← 个人共享 skills                                                                                                                                              
  ~/.openclaw/skills          ← 本地 managed skills                                                                                                                                          
  内置 bundled skills         ← OpenClaw 自带的                                                                                                                                              
  skills.load.extraDirs       ← 额外配置的目录

10. FAQ 与文档

卸载

卸载过程

1
openclaw uninstall --all --yes --non-interactive

会执行

1
2
3
4
openclaw gateway stop
openclaw gateway uninstall
rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
rm -rf ~/.openclaw/workspace

删除客户端

1
npm rm -g openclaw

删除 systemd 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
# 停止并禁用服务
systemctl --user disable --now openclaw-gateway.service
# 删除服务配置文件
rm -f ~/.config/systemd/user/openclaw-gateway.service
# 刷新 systemd 配置
systemctl --user daemon-reload



# 多配置场景：替换为对应 profile 服务名
# systemctl --user disable --now openclaw-gateway-<profile>.service
# rm -f ~/.config/systemd/user/openclaw-gateway-<profile>.service
# systemctl --user daemon-reload

备注

对接 dingtalk https://github.com/largezhou/openclaw-dingtalk

1
openclaw plugins install @largezhou/ddingtalk

当前使用的 openclaw.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
{
  "meta": {
    "lastTouchedVersion": "2026.4.8",
    "lastTouchedAt": "2026-04-16T10:22:00.014Z"
  },
  "env": {
    "shellEnv": {
      "enabled": true,
      "timeoutMs": 30000
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "apiKey": "xxx",
        "api": "anthropic-messages",
        "authHeader": true,
        "models": [
          {
            "id": "MiniMax-M2.7",
            "name": "MiniMax M2.7",
            "reasoning": true,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.06,
              "cacheWrite": 0.375
            },
            "contextWindow": 204800,
            "maxTokens": 131072,
            "api": "anthropic-messages"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.7"
      },
      "workspace": "/data/home/weilai/.openclaw/workspace",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      }
    },
    "list": [
      {
        "id": "default",
        "default": true,
        "name": "openclaw Agent",
        "workspace": "/data/home/weilai/.openclaw/workspace",
        "model": "minimax/MiniMax-M2.7",
        "skills": []
      }
    ]
  },
  "commands": {
    "native": true,
    "nativeSkills": true,
    "bash": true,
    "restart": true,
    "ownerDisplay": "raw"
  },
  "hooks": {
    "enabled": true,
    "path": "/hooks/",
    "allowRequestSessionKey": true,
    "token": "xxx"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "xxx"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    },
    "controlUi": {
      "allowedOrigins": [
        "*"
      ],
      "dangerouslyDisableDeviceAuth": true,
      "allowInsecureAuth": true
    }
  },
  "skills": {
    "entries": {}
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true,
        "config": {}
      },
      "minimax": {
        "enabled": true,
        "config": {}
      },
      "ddingtalk": {
        "enabled": true,
        "config": {}
      }
    },
    "installs": {
      "dingtalk": {
        "source": "path",
        "sourcePath": "/data/home/weilai/.openclaw/openclaw-channel-dingtalk",
        "installPath": "/data/home/weilai/.openclaw/openclaw-channel-dingtalk",
        "version": "3.5.3",
        "installedAt": "2026-04-16T07:34:16.702Z"
      }
    },
    "allow": [
      "ddingtalk"
    ]
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "bindings": [
    {
      "agentId": "default",
      "match": {
        "channel": "feishu",
        "accountId": "default"
      }
    },
    {
      "agentId": "default",
      "match": {
        "channel": "dingtalk",
        "accountId": "default"
      }
    }
  ],
  "tools": {
    "profile": "full"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "open",
      "groupPolicy": "open",
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "allowFrom": [
        "*"
      ]
    },
    "ddingtalk": {
      "enabled": true,
      "clientId": "dingxxx",
      "clientSecret": "LyLcy45TVqxxx",
      "allowFrom": [
        "*"
      ]
    }
  },
  "wizard": {
    "lastRunAt": "2026-04-16T10:04:15.908Z",
    "lastRunVersion": "2026.4.8",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  }
}