# 基本指令

* 首次
  ```bash
  openclaw onboard --install-daemon
  ```

* 配置
  openclaw configure

* 查看状态
  ```bash
  openclaw status
  ```
* 打开控制台界面
  ```bash
  openclaw dashboard
  ```
* 打开终端TUI
  ```bash
  openclaw tui
  ```
* 查看实时日志
  ```bash
  openclaw logs --follow
  ```
* 重启Gateway
  ```bash
  openclaw gateway restart
  ```
* 停止服务
  ```bash
  openclaw gateway stop
  ```
* 启动服务
  ```bash
  openclaw gateway start
  ```
* 查看服务状态
  ```bash
  openclaw gateway status
  ```
* 检查
  ```bash
  openclaw doctor --fix
  ```
* 配对
  ```
  openclaw devices list
  ```
* 批准
  ```
  openclaw devices approve req-xxx
  ```

# 升级

## 更新前必做：备份配置

```bash

# 一键备份整个 .openclaw 目录

cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)

# 重点文件：
# ~/.openclaw/agents/main/agent/auth-profiles.json — API Key 配置
# ~/.openclaw/agents/main/skills/                   — 已安装技能
# ~/.openclaw/config.yaml                           — 全局配置

```

## 若更新失败需要恢复

```bash
# 恢复备份
rm -rf ~/.openclaw
cp -r ~/.openclaw.backup-20260315 ~/.openclaw

```

## NPM升级

### 第一步：先尝试「在 OpenClaw 目录下直接全量安装依赖」（最推荐）
`openclaw doctor --fix` 本质是在 OpenClaw 的全局安装目录下执行 `npm install`，你可以手动执行这个操作，更可控：

1. **确认并进入 OpenClaw 全局安装目录**（和之前装 `@discordjs/opus` 是同一个目录）：
   ```bash
   # 先找到路径
   npm root -g
   # 进入该路径下的 openclaw 目录，例如：
   cd /usr/local/lib/node_modules/openclaw  # macOS/Linux 示例
   # 或
   cd $env:APPDATA\npm\node_modules\openclaw  # Windows PowerShell 示例
   ```

2. **确保使用国内 npm 镜像**（解决网络超时问题）：
   ```bash
   npm config set registry https://registry.npmmirror.com
   npm config set disturl https://npmmirror.com/mirrors/node/
   ```

3. **直接执行全量依赖安装**（这会自动安装 `package.json` 里列出的所有缺失依赖）：
   ```bash
   npm install
   ```
   安装完成后，再运行 `openclaw doctor` 检查是否恢复正常。

---

### 第二步：如果上面仍失败，尝试「完全重装 OpenClaw」
如果 OpenClaw 的全局安装目录已损坏，最彻底的方法是卸载后重装：

1. **完全卸载 OpenClaw**：
   ```bash
   npm uninstall -g openclaw
   ```

2. **清理 npm 缓存（确保无残留）**：
   ```bash
   npm cache clean --force
   ```

3. **重新安装最新版 OpenClaw**（安装时会自动拉取所有依赖）：
   ```bash
   # 先确保用国内镜像
   npm config set registry https://registry.npmmirror.com

   # 原始路径
   npm config set registry https://registry.npmjs.org/
   # 再安装
   npm install -g openclaw@latest
   ```

4. **安装完成后验证**：
   ```bash
   openclaw doctor
   ```

---

### 第三步：排查「npm 权限问题」（如果是 macOS/Linux）
如果你在执行 `npm install` 时遇到 `EACCES` 权限错误，说明 npm 全局目录权限有问题，不要用 `sudo` 强行安装，建议修复权限：

1. **查看 npm 全局目录所有者**：
   ```bash
   ls -la $(npm root -g)
   ```
   如果所有者是 `root` 而不是你的用户名，需要修改：

2. **修改 npm 全局目录所有者为当前用户**：
   ```bash
   sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
   ```
   然后再回到 OpenClaw 目录执行 `npm install`。

---

### 避坑提醒
- **不要手动一个个装**：这些依赖之间有版本依赖关系，手动装容易导致版本冲突，`npm install` 会自动处理版本兼容。
- **优先用国内镜像**：很多依赖（如 `@aws-sdk`、`@discordjs`）在国内直接从 npm 官方源下载很慢，容易超时失败。

先试试第一步的「在 OpenClaw 目录下直接 npm install」，大部分情况下能直接解决问题。


## 升级指令

```bash

# Step 1：停止 Gateway（避免更新过程中文件被占用）
openclaw gateway stop

# Step 2：执行更新（更新到 stable 最新版）
openclaw update --channel stable

# Step 3：重启 Gateway
openclaw gateway start

# Step 4：验证更新结果
openclaw --version
openclaw doctor
```