
#ubuntu #openclaw #install #uninstall

```table-of-contents
```

## 环境概述

- 系统：Ubuntu 20.04 / 22.04
- OpenClaw 安装方式：npm 用户本地全局安装openclaw & clawhub (注意不要用root user安装)
```
npm install -g openclaw clawhub
```
- 用户路径示例： 

```bash
/home/shenwei/.npm-global/bin/openclaw
```

- 默认配置目录：
```bash
/home/shenwei/.openclaw
```

- 用户级 systemd 服务目录：
```bash
/home/shenwei/.config/systemd/user/openclaw-gateway.service
```

---

## 卸载旧版本 OpenClaw

1. **停止正在运行的进程 / 服务**
```bash
# 查找进程
ps aux | grep openclaw

# 如果有 systemd 用户服务
systemctl --user stop openclaw
systemctl --user disable openclaw
```

2. **卸载 npm 安装的 OpenClaw**
```bash
# 全局卸载
sudo npm uninstall -g openclaw clawhub

# 或者局部卸载
npm uninstall openclaw clawhub
```

3. **删除用户配置目录**
```bash
rm -rf /home/shenwei/.openclaw        # 普通用户
sudo rm -rf /root/.openclaw           # root 用户（如果曾用 sudo 运行）
sudo rm -rf /opt/openclaw             # 如果之前手动统一过目录
```

4. **清理残留 npm 包**
```bash
npm list -g --depth=0 | grep openclaw
npm list -g --depth=0 | grep clawhub
```
如有残留再执行 `npm uninstall -g <package>`。

---

## 安装 OpenClaw

### 方法 A：通过 npm 安装（推荐）

```bash
# 确保 npm 更新
npm install -g npm

# 全局安装 OpenClaw
npm install -g openclaw clawhub
```

---

## 配置 PATH，让 OpenClaw 在任意位置可执行

1. 临时生效（仅当前终端）：
```bash
export PATH=$HOME/.npm-global/bin:$PATH
```

2. 永久生效（推荐）：
- 编辑 shell 配置文件 `~/.bashrc` 或 `~/.zshrc`，添加：
```bash
export PATH=$HOME/.npm-global/bin:$PATH
```

- 刷新配置：
```bash
source ~/.bashrc   # bash
source ~/.zshrc    # zsh
```

- 验证：
```bash
which openclaw
openclaw --version
```
---

## 用户级 systemd 服务管理（OpenClaw Gateway）

安装 Gateway 后会生成服务文件：
```bash
/home/shenwei/.config/systemd/user/openclaw-gateway.service
```

``` bash
[Unit]
Description=OpenClaw Gateway (v2026.3.13)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/bin/node /home/shenwei/.npm-global/lib/node_modules/openclaw/dist/index.js gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group
Environment=HOME=/home/shenwei
Environment=TMPDIR=/tmp
Environment=HTTP_PROXY=http://127.0.0.1:10808
Environment=HTTPS_PROXY=http://127.0.0.1:10808
Environment=PATH=/home/shenwei/.local/bin:/home/shenwei/.npm-global/bin:/home/shenwei/bin:/home/shenwei/.volta/bin:/home/shenwei/.asdf/shims:/home/shenwei/.bun/bin:/>
Environment=OPENCLAW_GATEWAY_PORT=18789
Environment=OPENCLAW_SYSTEMD_UNIT=openclaw-gateway.service
Environment="OPENCLAW_WINDOWS_TASK_NAME=OpenClaw Gateway"
Environment=OPENCLAW_SERVICE_MARKER=openclaw
Environment=OPENCLAW_SERVICE_KIND=gateway
Environment=OPENCLAW_SERVICE_VERSION=2026.3.13

[Install]
WantedBy=default.target

```

查看日志
```

# 查看最近 50 行
journalctl --user -u openclaw-gateway -n 50 --no-pager

# 实时跟踪日志
journalctl --user -u openclaw-gateway -f

# 查看今天的所有日志
journalctl --user -u openclaw-gateway --since today
```


### 常用管理命令

| 操作                          | 命令                                          |
| --------------------------- | ------------------------------------------- |
| 启动 Gateway                  | `systemctl --user start openclaw-gateway`   |
| 停止 Gateway                  | `systemctl --user stop openclaw-gateway`    |
| 重启 Gateway                  | `systemctl --user restart openclaw-gateway` |
| 查看状态                        | `systemctl --user status openclaw-gateway`  |
| 开机自启                        | `systemctl --user enable openclaw-gateway`  |
| 取消开机自启                      | `systemctl --user disable openclaw-gateway` |
| 刷新 systemd 配置（修改 service 后） | `systemctl --user daemon-reload`            |


> ⚠️ 用户级服务不需要 sudo，安全且方便。

---

## 多用户环境与避免重复环境

- OpenClaw 配置目录默认跟随 `$HOME`：

|用户|配置目录|
|---|---|
|shenwei|`/home/shenwei/.openclaw`|
|root|`/root/.openclaw`|

- **原因**：Linux 用户隔离机制，不同用户运行 OpenClaw 会生成独立目录。
- **注意**：
    
    - 不要用 root 启动 OpenClaw，避免权限混乱
    - 统一使用普通用户安装和运行
    - 可通过 `--workdir /opt/openclaw` 指定统一目录


---

## 常用命令总结

| 命令                                                                    | 功能            |
| --------------------------------------------------------------------- | ------------- |
| `openclaw onboard`                                                    | 初始化新环境、设置工作目录 |
| `openclaw --version`                                                  | 查看版本          |
| `openclaw agent list`                                                 | 列出所有 agent    |
| `openclaw agent create --name <agent_name> --message "<description>"` | 创建新的 agent    |
| `openclaw agent delete <agent_name>`                                  | 删除 agent      |
| `openclaw skill install <skill_name>`                                 | 安装技能          |
| `openclaw skill update <skill_name>`                                  | 更新技能          |
| `openclaw skill list`                                                 | 查看已安装技能       |
| `openclaw memory list`                                                | 查看记忆数据        |
| `openclaw workspace list`                                             | 查看工作空间        |
|                                                                       |               |
|                                                                       |               |

---

## 创建 Agent 与绑定 Telegram Bot

1. **创建 agent**
```
openclaw agents add <agentname> --non-interactive --workspace /home/shenwei/.openclaw/workspace-agent-<agentname> --model MiniMax-M2.5

```
举例：
```bash
openclaw agents add yunce --non-interactive --workspace /home/shenwei/.openclaw/workspace-agent-yunce --model MiniMax-M2.5
```

2. **添加Telegram 账号**
```
# 添加 Telegram 账号
openclaw channels add --channel telegram --account <账号名> --token <BotToken>
```
举例
```
openclaw channels add --channel telegram --account yunhan --token 8588117769:AAFxswhHgCdBor2EOa-2oChDpI-DADRt0tQ
```
3. **查看 agent 列表**
```bash
openclaw agents list
```

3. **绑定 Bot**
```
# 绑定 agent 到 Telegram 账号
openclaw agents bind --agent <agent_id> --bind telegram:<account_name>

```
举例
```
openclaw agents bind --agent yunhan --bind telegram:yunhan
```

- 配置完成后重启 Gateway：
```bash
systemctl --user restart openclaw-gateway
```

- Telegram 多 Agent 建议：
    
    - 一个 bot → n8n 路由 → 多 agent
    - 避免每个 agent 都创建独立 bot（每个账号最多 20 个 bot）
    - 用命令或路径路由区分不同 agent 功能

---

## 删除Agent
1. **删除 agent**
```
openclaw agents delete <agent_name> --force
```
2. **删除bot**
```
# 删除 Telegram 账号
openclaw channels remove --channel telegram --account <account_name> --delete
```

## 注意事项与避免的坑

1. **避免使用 root 运行**
    - root 会生成 `/root/.openclaw`，和普通用户环境冲突
    - 权限问题可能导致 agent 无法访问工作空间
2. **避免重复 PATH 或多版本冲突**
    - 如果 npm 本地 bin 不在 PATH，会导致命令找不到
    - 如果 PATH 里还有旧版本系统全局安装路径，可能会调用错误版本
3. **用户级 systemd 服务管理**
    - 修改 service 后必须执行 `systemctl --user daemon-reload`
    - 避免 sudo 启动服务，保证文件权限正确
4. **Telegram Bot 限制**
    - 每个账号最多创建 20 个 bot（Premium 账号可能 40 个）
    - 多 agent 架构建议一个 bot → n8n → 多 agent 路由
5. **统一工作目录**
    - 推荐 `/home/shenwei/.openclaw` 或 `/opt/openclaw`
    - 方便多服务器或多 agent 管理
6. **升级和维护**
    - 升级前先备份 `.openclaw` 下的 workspace、skills、memory
    - 使用 npm 全局安装可直接 `npm install -g openclaw@latest`

---

### 参考架构示意

```
Telegram Bot
     ↓
   n8n Router
     ↓
  OpenClaw Agents
  ├─ 星枢（调度）
  ├─ 星曜（IT管家）
  ├─ 星辉（个人助理）
  └─ 云瀚（监控）
```


### Bot & Agent 命名

#### 星

```
openclaw channels add --channel telegram --account xingshu --token 8787024183:AAG1M5tfSHj6Z0gMv3vvCZel2FOIX-0x8ZI

openclaw channels add --channel telegram --account xingyao --token 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk

openclaw channels add --channel telegram --account xinghui --token 8709222939:AAEfvZrvvU5vZFsmacsR5nmpkJ2Jb5JgfRg

```

| 服务器     | 角色  | Bot Name                     | Bot Key                                        | Agent Id | Telegram User ID |
| ------- | --- | ---------------------------- | ---------------------------------------------- | -------- | ---------------- |
| macmini | 星枢  | @shenwei_macmini_xingshu_bot | 8787024183:AAG1M5tfSHj6Z0gMv3vvCZel2FOIX-0x8ZI | main     | 5038825565       |
| macmini | 星曜  | @shenwei_macmini_xingyao_bot | 8414432613:AAG9hvKfILGSsbc1EMEZW1QVym9Quc5aHWk | xingyao  | 5038825565       |
| macmini | 星辉  | @shenwei_macmini_xinghui_bot | 8709222939:AAEfvZrvvU5vZFsmacsR5nmpkJ2Jb5JgfRg | xinghui  | 5038825565       |
|         |     |                              |                                                |          |                  |
#### 云

```
openclaw channels add --channel telegram --account yunhan --token 8588117769:AAFxswhHgCdBor2EOa-2oChDpI-DADRt0tQ

openclaw channels add --channel telegram --account yunce --token 8791231082:AAFKPfTPy3LshybWUJ0joBkz3Th3mwYQOnc

openclaw channels add --channel telegram --account yunjiang --token 8727937702:AAGw3WGPI1j5rSD97wap6h9EGqVpDEMdjLU

openclaw channels add --channel telegram --account yunzhi --token 8639619464:AAEI35Dnt-9PQ8y4Du_ToxVhwUBUa5kpLjU
```

| 服务器     | 角色  | Bot Name                      | Bot Key                                        | Agent 名称 | Telegram User ID |
| ------- | --- | ----------------------------- | ---------------------------------------------- | -------- | ---------------- |
| ubuntu2 | 云瀚  | @shenwei_ubuntu2_yunhan_bot   | 8588117769:AAFxswhHgCdBor2EOa-2oChDpI-DADRt0tQ | yunhan   | 5038825565       |
| ubuntu2 | 云策  | @shenwei_ubuntu2_yunce_bot    | 8791231082:AAFKPfTPy3LshybWUJ0joBkz3Th3mwYQOnc | yunce    | 5038825565       |
| ubuntu2 | 云匠  | @shenwei_ubuntu2_yunjiang_bot | 8727937702:AAGw3WGPI1j5rSD97wap6h9EGqVpDEMdjLU | yunjiang | 5038825565       |
| ubuntu2 | 云织  | @shenwei_ubuntu2_yunzhi_bot   | 8639619464:AAEI35Dnt-9PQ8y4Du_ToxVhwUBUa5kpLjU | yunzhi   | 5038825565       |


#### 风

```
openclaw channels add --channel telegram --account fengheng --token 

openclaw channels add --channel telegram --account fengchi --token 

openclaw channels add --channel telegram --account fengji --token 
```

| 服务器     | 角色  | Bot Name                      | Bot Key | Agent 名称 | Telegram User ID |
| ------- | --- | ----------------------------- | ------- | -------- | ---------------- |
| ubuntu1 | 风衡  | @shenwei_ubuntu1_fengheng_bot |         | fengheng | 5038825565       |
| ubuntu1 | 风驰  | @shenwei_ubuntu1_fengchi_bot  |         | fengchi  | 5038825565       |
| ubuntu1 | 风纪  | @shenwei_ubuntu1_fengji_bot   |         | fengji   | 5038825565       |
