Homeland Openclaw Chat

Name: Homeland Openclaw Chat
Rating: 3.5 (1 reviews)
Author: heyeokim-arch

By heyeokim-arch 👁 4 views ▲ 0 votes

Standalone Homeland OpenClaw chat plugin with setup guide

GitHub

Configuration Example

channels:
  homeland:
    enabled: true
    appId: "cb_xxxxxxxxxxxx"
    appSecret: "xxxxxxxxxxxxxxxx"
    callbackUrl: "https://yourdomain.com/openclaw/callbacks/messages"

README

# homeland-openclaw-chat-plugin

Homeland 社区端的 OpenClaw Chat 插件。

它为 Homeland 社区增加一个 `/openclaw` 聊天页面，支持用户在社区内直接和 AI 对话，并通过 OpenClaw 完成消息处理与回调。

## 功能

- 社区内聊天页面：`/openclaw`
- 用户可创建和管理自己的机器人
- 支持多机器人配置
- 支持快捷指令 `/new`、`/stop`、`/clear`、`/status`、`/summarize`
- OpenClaw 轮询待处理消息
- OpenClaw 回调 AI 回复到社区
- 所有 OpenClaw API 请求使用 `X-App-Id` 和 `X-OC-Signature` 签名
- 支持前端消息轮询刷新，避免刷新页面后才能看到回复

## 目录结构

```txt
app/
  channels/
  controllers/
  jobs/
  models/
  views/
config/
  locales/
  routes.rb
lib/
  openclaw_chat/
boot.rb
migrate/
```

## 运行原理

消息链路：

```txt
用户在 /openclaw 发消息
-> Homeland 写入 openclaw_messages，状态 queued
-> OpenClaw 轮询 /openclaw/api/messages/pending
-> OpenClaw 调用 /openclaw/api/messages/:id/ack
-> OpenClaw 生成 AI 回复
-> OpenClaw 回调 /openclaw/callbacks/messages
-> Homeland 写入 assistant 消息
-> 页面通过 ActionCable 或前端轮询看到新消息
```

## 主要接口

### 用户页面

- `GET /openclaw`
- `GET /openclaw/settings`
- `GET /openclaw/admin`

### 消息接口

- `GET /openclaw/bots/:bot_id/messages`
- `POST /openclaw/bots/:bot_id/messages`
- `DELETE /openclaw/bots/:bot_id/messages/:id`
- `DELETE /openclaw/bots/:bot_id/messages/bulk_destroy`
- `GET /openclaw/bots/:bot_id/messages/newer?after=:id`

### OpenClaw 对接接口

- `GET /openclaw/api/messages/pending`
- `POST /openclaw/api/messages/:id/ack`
- `POST /openclaw/callbacks/messages`

## 安装到 Homeland

把本项目放到 Homeland 的 `plugins/openclaw_chat/` 目录。

```bash
cd /path/to/homeland
mkdir -p plugins
cp -R /path/to/homeland-openclaw-chat-plugin plugins/openclaw_chat
```

然后确保 Homeland 会加载插件。

## 数据库迁移

本插件包含这些迁移：

- `create_openclaw_bots`
- `create_openclaw_conversations`
- `create_openclaw_messages`
- `add_user_id_to_openclaw_bots`
- `add_app_credentials_to_openclaw_bots`

把迁移复制或链接到 Homeland 后执行：

```bash
bundle exec rails db:migrate RAILS_ENV=production
```

## 配置

### 1. 启用插件

插件注册信息在 `boot.rb`，根路径为 `/openclaw`。

后台可通过 `openclaw_enabled` 控制开关。

### 2. 创建机器人

登录社区后进入：

```txt
/openclaw/settings
```

创建机器人后会生成：

- App ID
- App Secret

这两个值用于 OpenClaw 端配置。

### 3. OpenClaw 回调地址

把社区地址配置给 OpenClaw：

```txt
https://yourdomain.com/openclaw/callbacks/messages
```

## 与 OpenClaw 配合使用

OpenClaw 端需要安装独立扩展：

- 项目名：`openclaw-homeland-extension`

配置示例：

```yaml
channels:
  homeland:
    enabled: true
    appId: "cb_xxxxxxxxxxxx"
    appSecret: "xxxxxxxxxxxxxxxx"
    callbackUrl: "https://yourdomain.com/openclaw/callbacks/messages"
```

多机器人示例：

```yaml
channels:
  homeland:
    enabled: true
    accounts:
      bot1:
        name: "客服助手"
        appId: "cb_aaa"
        appSecret: "secret_aaa"
        callbackUrl: "https://yourdomain.com/openclaw/callbacks/messages"
      bot2:
        name: "技术顾问"
        appId: "cb_bbb"
        appSecret: "secret_bbb"
        callbackUrl: "https://yourdomain.com/openclaw/callbacks/messages"
```

## 开发说明

关键文件：

- `boot.rb`：插件注册
- `config/routes.rb`：所有路由
- `app/controllers/openclaw_chat/api_controller.rb`：OpenClaw 拉取待处理消息
- `app/controllers/openclaw_chat/callbacks_controller.rb`：接收 OpenClaw 回调
- `app/controllers/openclaw_chat/messages_controller.rb`：消息 CRUD 和 `newer` 轮询接口
- `app/views/openclaw_chat/home/index.html.erb`：前端聊天页面
- `app/channels/openclaw_chat_channel.rb`：ActionCable 频道

## 版本

当前版本：`0.1.0`

## 说明

这个仓库只包含 Homeland 侧插件源码。
OpenClaw 侧对接扩展请查看独立项目 `openclaw-homeland-extension`。

tools