# OpenClaw EC2 部署教程

脚本位置：`/home/ssm-user/openclaw-deploy.sh`（EC2 上）

## 快速部署（3 步）

```bash
# 1. SSH 到 EC2（或 SSM 交互会话）
aws ssm start-session --target <instance-id> --profile openclaw --region eu-west-1

# 2. 运行脚本，跟着提示走
cd /home/ssm-user
bash openclaw-deploy.sh

# 3. 输入你的实例名（不要和别人重复），等待构建完成
```

首次构建约 5-8 分钟，之后复用镜像秒级启动。

## 部署完成后访问

部署结束会打印类似：

```
Dashboard: http://127.0.0.1:21325/#token=abc123...
```

**你不能直接在浏览器打开这个地址**——需要先做端口转发。

### 端口转发（在本地 Mac/PC 终端执行）

```bash
aws ssm start-session \
  --target <ec2-instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["<脚本输出的端口>"],"localPortNumber":["<同一个端口>"]}' \
  --profile openclaw \
  --region eu-west-1
```

例如脚本输出端口是 `21325`：

```bash
aws ssm start-session \
  --target i-02efb9e67df771ea9 \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["21325"],"localPortNumber":["21325"]}' \
  --profile openclaw \
  --region eu-west-1
```

保持这个终端不要关，然后浏览器打开脚本输出的完整 Dashboard URL。

### 设备配对（pairing required）

浏览器首次打开会显示 `pairing required`。在 EC2 上执行：

```bash
bash openclaw-deploy.sh pair-device --instance <你的实例名> --yes
```

然后**刷新浏览器**即可。

## 配置模型

部署完成后 OpenClaw 还没有可用的 AI 模型，需要手动配置一个。

### OpenAI

```bash
bash openclaw-deploy.sh configure-model --instance <name> \
  --provider openai \
  --api-key sk-xxx \
  --primary-model openai/gpt-5.4
```

### Anthropic

```bash
bash openclaw-deploy.sh configure-model --instance <name> \
  --provider anthropic \
  --api-key sk-ant-xxx \
  --primary-model anthropic/claude-sonnet-4-6
```

### OpenRouter

```bash
bash openclaw-deploy.sh configure-model --instance <name> \
  --provider openrouter \
  --api-key sk-or-xxx \
  --primary-model openrouter/anthropic/claude-sonnet-4-6
```

### 其他 provider

支持 `bedrock`、`bailian`、`custom`。自定义 provider 需要额外参数：

```bash
bash openclaw-deploy.sh configure-model --instance <name> \
  --provider custom \
  --api-key xxx \
  --base-url https://your-api.example.com/v1 \
  --primary-model your-model-id
```

### 可选参数

| 参数 | 说明 |
|------|------|
| `--primary-model` | 主模型 ID |
| `--fallbacks model1,model2` | 备选模型（逗号分隔） |
| `--image-model modelRef` | 图像生成模型 |
| `--allowlist model1,model2` | 模型白名单 |

配置完成后验证：

```bash
bash openclaw-deploy.sh doctor --instance <name>
```

## 非交互部署（SSM Run Command）

适合自动化场景，不需要人工输入：

```bash
bash openclaw-deploy.sh deploy --instance alice --non-interactive
```

## 常用命令速查

| 操作 | 命令 |
|------|------|
| 查看状态 | `bash openclaw-deploy.sh status --instance <name>` |
| 查看日志 | `bash openclaw-deploy.sh logs --instance <name>` |
| 健康检查 | `bash openclaw-deploy.sh doctor --instance <name>` |
| 重启服务 | `bash openclaw-deploy.sh restart --instance <name>` |
| 设备配对 | `bash openclaw-deploy.sh pair-device --instance <name> --yes` |
| 配置模型 | `bash openclaw-deploy.sh configure-model --instance <name> --provider openai --api-key sk-xxx --primary-model openai/gpt-5.4` |
| 配置频道 | `bash openclaw-deploy.sh configure-channel --instance <name> --channel telegram --token xxx` |
| 删除实例 | `bash openclaw-deploy.sh remove --instance <name> --purge-data --yes` |
| 列出所有实例 | `bash openclaw-deploy.sh list-instances` |

## 故障排查

### 浏览器打不开 / Connection refused

1. 确认端口转发终端还活着
2. 确认端口号和脚本输出一致
3. 在 EC2 上测试：`curl -sf http://127.0.0.1:<端口>/healthz` — 如果这里也不通，容器可能没启动
4. 查日志：`bash openclaw-deploy.sh logs --instance <name>`

### pairing required 反复出现

```bash
# 先刷新浏览器页面，再执行：
bash openclaw-deploy.sh pair-device --instance <name> --yes
```

如果仍然不行（极端情况），临时关闭设备认证：

```bash
bash openclaw-deploy.sh repair-control-ui --instance <name>
# 问题解决后恢复：
bash openclaw-deploy.sh repair-control-ui --instance <name> --revert
```

### 锁文件权限错误

如果看到 `Permission denied` 关于 lock 文件：

```bash
# 用 root 修复权限
sudo chown -R ssm-user:ssm-user /home/ssm-user/openclaw/locks/
```

### Docker buildx 权限错误

```bash
sudo chown -R ssm-user:ssm-user /home/ssm-user/.docker/
```

这类权限问题通常是因为之前有人用 root（SSM send-command）跑过脚本。

## 实例名规则

每个人**必须用自己的实例名**，不要和别人重复。

推荐：`alice`、`bob`、`zhangsan`、`team-a-dev`

不推荐：`test`、`main`、`default`（容易撞车）

## 完整工作流示例

### 从零部署到浏览器访问

```bash
# EC2 上
cd /home/ssm-user
bash openclaw-deploy.sh
# 选择 1（本地部署），输入实例名，等待完成
# 记下输出的 Dashboard URL 和端口号
```

```bash
# 本地 Mac/PC — 新终端窗口
aws ssm start-session \
  --target <ec2-instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["<端口>"],"localPortNumber":["<端口>"]}' \
  --profile openclaw --region eu-west-1
```

```bash
# 浏览器打开 Dashboard URL → 如果 pairing required：
# EC2 上执行
bash openclaw-deploy.sh pair-device --instance <name> --yes
# 刷新浏览器
```

### 删除重建

```bash
bash openclaw-deploy.sh remove --instance <name> --purge-data --yes
bash openclaw-deploy.sh deploy --instance <name> --non-interactive
```


### 备注

当前EC2的 docker版本较老，缺少组件，所以只能用sudo执行脚本，设备配对也需要sudo