Plugin Slack Proxy

Name: Plugin Slack Proxy
Rating: 3.5 (1 reviews)
Author: bigheadfjuee

By bigheadfjuee 👁 1 views ▲ 0 votes

OpenClaw Slack integration plugin with HTTPS proxy support for Socket Mode

GitHub

Install

npm install
```

Configuration Example

import SlackProxyPlugin from './src/plugin.js';

const plugin = new SlackProxyPlugin();

// 初始化
await plugin.initialize();

// 啟動
await plugin.start();

// 停止
await plugin.stop();

// 取得資訊
const info = plugin.getInfo();

README

# OpenClaw Slack Proxy Plugin

OpenClaw 的 Slack 整合插件，提供 Socket Mode 即時事件連線，支援公司內部網路 Proxy。

[English](./README.en.md) | **繁體中文**

## 功能特性

- 🔌 **Socket Mode 連線** - 即時接收 Slack 事件
- 🤖 **Bot 整合** - 自動回覆訊息、處理 @mention 和反應
- 🌐 **Proxy 支援** - 支援公司內部網路 HTTP/HTTPS Proxy
- 🔄 **自動重連** - Socket 中斷時自動重新連線
- 📝 **模組化設計** - 易於擴展自訂事件處理器
- ✅ **完整測試** - 包含單元測試和 CI/CD 工作流

## 需求條件

- Node.js >= 18.0.0
- npm 或 yarn
- Slack 工作區管理員權限
- 公司 Proxy 認證資訊（如適用）

## 快速開始

### 1. 複製或下載本專案

```bash
git clone https://github.com/yourusername/openclaw-plugin-slack-proxy.git
cd openclaw-plugin-slack-proxy
npm install
```

### 2. 設置 Slack App

在 [Slack API 介面](https://api.slack.com/apps) 中：

#### 建立應用程式
1. 點選 "Create New App"
2. 選擇 "From scratch"
3. 輸入應用名稱和工作區

#### 啟用 Socket Mode
1. 左側導覽列選 "Socket Mode"
2. 點選 "Enable Socket Mode"
3. 複製 **App-Level Tokens**（以 `xapp-` 開頭）

#### 設置 Scopes
1. 左側導覽列選 "OAuth & Permissions"
2. 在 "Scopes" 下添加以下 Bot Token Scopes：
   - `chat:write` - 傳送訊息
   - `chat:write.public` - 在公開頻道傳送訊息
   - `chat:write.customize` - 自訂訊息
   - `reactions:read` - 讀取反應
   - `messages:read` - 讀取訊息
   - `users:read` - 讀取用戶資訊

#### 訂閱 Events
1. 左側導覽列選 "Event Subscriptions"
2. 啟用 Events
3. 訂閱以下 Bot Events：
   - `message.channels`
   - `app_mention`
   - `reaction_added`
   - `reaction_removed`

#### 取得 Bot Token
1. 返回 "OAuth & Permissions"
2. 複製 **Bot User OAuth Token**（以 `xoxb-` 開頭）
3. 安裝應用到工作區

### 3. 環境設置

複製 `.env.example` 並建立 `.env` 檔案：

```bash
cp .env.example .env
```

編輯 `.env` 並填入 Slack tokens：

```env
# Slack 認證
SLACK_APP_TOKEN=xapp-1-xxxxxxxxxxxx
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx

# Proxy 設定（如果需要）
HTTPS_PROXY=http://proxy.company.com:8080

# 可選設定
NODE_ENV=production
DEBUG=false
```

### 4. 安裝依賴並啟動

```bash
npm install
npm start
```

你應該看到：

```
╔════════════════════════════════════════╗
║  Slack Proxy Plugin - Initializing     ║
╚════════════════════════════════════════╝

✓ 環境變數驗證通過
✓ 初始化 Socket Mode 客戶端...
✓ 初始化 Web API 客戶端...
✓ 插件初始化完成

🚀 啟動 Slack Proxy Plugin...

🔌 Socket Mode 連線中...
✓ Socket Mode 已連線
✓ Slack Proxy Plugin 已啟動並運行中
```

## Proxy 支援

### 配置公司 Proxy

在 `.env` 中設置：

```env
# 標準 HTTP/HTTPS Proxy
HTTPS_PROXY=http://proxy.company.com:8080

# 帶認證的 Proxy
HTTPS_PROXY=http://username:[email protected]:8080
```

支援的環境變數：
- `HTTPS_PROXY` / `https_proxy`
- `HTTP_PROXY` / `http_proxy`

### 驗證 Proxy 連線

應用會自動檢測並報告 Proxy 設置：

```
✓ Proxy 已配置: http://proxy.company.com:***
```

密碼會自動隱藏以確保安全。

## 專案結構

```
openclaw-plugin-slack-proxy/
├── src/
│   ├── plugin.js           # OpenClaw 插件入點
│   ├── slack-client.js     # Slack 連線邏輯
│   ├── proxy-config.js     # Proxy 設定管理
│   └── handlers/
│       └── message.js      # 訊息事件處理
├── tests/
│   └── plugin.test.js      # 單元測試
├── .github/
│   └── workflows/
│       └── ci.yml          # GitHub Actions CI/CD
├── .env.example            # 環境變數範本
├── package.json
└── README.md              # 本檔案
```

## API 文件

### SlackProxyPlugin 類

主要插件類，提供 OpenClaw 整合介面。

```javascript
import SlackProxyPlugin from './src/plugin.js';

const plugin = new SlackProxyPlugin();

// 初始化
await plugin.initialize();

// 啟動
await plugin.start();

// 停止
await plugin.stop();

// 取得資訊
const info = plugin.getInfo();
```

### 事件處理器

在 `src/handlers/message.js` 中添加自訂處理器：

```javascript
export async function handleCustomEvent(event, ack, webClient) {
  await ack();
  // 你的邏輯
}
```

然後在 `plugin.js` 的 `_handleEventsApi` 方法中註冊。

### Proxy 工具函數

```javascript
import { 
  createProxyAgent,
  validateProxyConfig,
  getSlackClientOptions 
} from './src/proxy-config.js';

// 建立 Proxy Agent
const agent = createProxyAgent();

// 驗證 Proxy 配置
const config = validateProxyConfig();

// 取得 Slack 客戶端選項
const options = getSlackClientOptions();
```

## 開發指南

### 執行測試

```bash
npm test
```

### 代碼格式化

```bash
npm run format
```

### 代碼檢查

```bash
npm run lint
```

### 開發模式

```bash
npm run dev
```

## 故障排除

### 連線問題

**問題**: `Socket Mode 連線中...` 但無法連線

**解決方案**:
1. 檢查 `SLACK_APP_TOKEN` 是否正確（應以 `xapp-` 開頭）
2. 確認 App 已在 Slack 中安裝到工作區
3. 檢查是否有 Proxy 問題

```bash
# 測試 Proxy 連線
curl -x http://proxy.company.com:8080 https://slack.com
```

### Proxy 認證失敗

**問題**: `HttpsProxyError: 407 Proxy Authentication Required`

**解決方案**:
1. 確認 Proxy 認證資訊正確
2. 確保用戶名和密碼已正確 URL 編碼
3. 聯絡網路管理員確認 Proxy 存取

### 訊息未送出

**問題**: 應用連線成功但訊息未送出

**解決方案**:
1. 檢查 `SLACK_BOT_TOKEN` 是否正確
2. 檢查 Bot 是否已加入相應頻道
3. 檢查應用 scopes 是否包含 `chat:write`

## 安全最佳實踐

1. **絕不提交 `.env` 檔案** - 使用 `.env.example` 作為範本
2. **定期更新依賴** - 執行 `npm audit` 檢查漏洞
3. **隱藏敏感資訊** - logs 自動隱藏 Proxy 密碼
4. **使用 App-level tokens** - 不要使用用戶 tokens

## 貢獻指南

1. Fork 本倉庫
2. 建立 feature 分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 開啟 Pull Request

## 授權協議

MIT License - 詳見 [LICENSE](./LICENSE) 檔案

## 聯絡方式

- 📧 Email: [email protected]
- 🐙 GitHub: [github.com/yourusername](https://github.com/yourusername)
- 💬 Slack: @tony

## 感謝

- [Slack API](https://api.slack.com/)
- [OpenClaw](https://github.com/bigheadfjuee/openclaw)
- [tony-slack](https://github.com/bigheadfjuee/tony-slack) 專案啟發

## 更新日誌

### v1.0.0 (2026-03-26)

- ✨ 初始版本
- 🔌 Socket Mode 支援
- 🌐 Proxy 支援
- 📝 完整文件和測試
- 🚀 GitHub Actions CI/CD

---

**Made with ❤️ for OpenClaw**

channels