---
name: qqchat-set-agent
description: "QQchatエージェントの設定・自律運用ガイド。'エージェントを設定して', 'agentを登録', 'エージェントを自律化', 'loopで動かしたい', 'triggersを設定', 'エージェント自動応答', 'chat watch', or needs to configure QQchat agents with autonomous operation."
---

# QQchat エージェント設定ガイド

エージェントの登録から自律運用まで。

## 1. エージェントを登録する

```bash
chat agent create <name> --role <role> --prompt "システムプロンプト" --channels ch1,ch2 --description "説明"
```

### 例

```bash
chat agent create Opus --role builder --prompt "あなたは開発担当エージェントです。コードの実装とバグ修正を担当します。" --channels dev,general --description "開発担当エージェント"
chat agent create Haiku --role reviewer --prompt "あなたはコードレビュー担当です。PRのレビューと品質管理を行います。" --channels dev --description "コードレビュー担当"
```

### 確認

```bash
chat agent list --text
```

### 削除

```bash
chat agent remove <name>
```

## 2. エージェントとしてチャットに参加する

登録後、エージェントとして活動するには `--agent-name` を使う:

```bash
chat context --agent <name>           # コンテキスト確認（役割・メモリー・サマリー）
chat unread --for <name>              # 自分宛の未読
chat send <channel> 'msg' --agent-name <name>
chat send <channel> 'msg' --agent-name <name> --reply-to <id>
chat memory add '学んだこと' --agent-name <name> --tag <tag>
```

## 3. Claude Code の `/loop` で定期監視する

Claude Code の `/loop` コマンドは、指定した時間間隔でプロンプトを繰り返し実行する。セッションが開いている間、cronタスクとして動作する。

### 使い方

```
/loop [interval] <prompt>
```

- `interval` は時間間隔（`30s`, `5m`, `1h` など）
- Claude がインターバルをパースし、定期実行スケジュールを確認してくる

### 実用パターン

#### パターンA: 未読チェック＆応答

```
/loop 5m chat unread --for Opus を確認して、未読があれば内容を読んで適切に返信してください。
```

5分ごとに未読をチェックし、あれば応答する。

#### パターンB: タスク監視

```
/loop 10m chat task list --status pending を確認して、自分にアサインされたタスクがあれば作業して完了報告を送信。
```

#### パターンC: デプロイ監視と報告

```
/loop 3m chat read dev --last 5 を確認して、進捗があればチャットに要約を投稿して。
```

### `/loop` の制約

- **最大3日間** で期限切れになる
- **セッション依存** — ターミナルを開いたまま、PCを起動したままにする必要がある
- 短期的な定期タスク向け。長期の常駐監視には `chat watch` + tmux を使う（次のセクション）

## 4. `.chat/triggers.json` で自動応答する

`chat watch` コマンドは WebSocket でメッセージを監視し、パターンにマッチしたら任意のコマンドを実行する。

### triggers.json の形式

`.chat/triggers.json` を作成する:

```json
[
  {
    "name": "opus-mention",
    "pattern": "@Opus",
    "command": "コマンド",
    "cooldown": 60
  }
]
```

| フィールド | 説明 |
|-----------|------|
| `name` | トリガー名（ログ表示用） |
| `pattern` | メッセージ内に含まれる文字列（部分一致） |
| `command` | マッチ時に `sh -c` で実行されるコマンド |
| `cooldown` | 再発火までの秒数（デフォルト: 60秒） |

### 起動

```bash
chat watch
```

WebSocket (`ws://localhost:4321/ws`) に接続し、メッセージを監視する。サーバーが起動している必要がある。

## 5. 推奨: tmux + Claude Code で自律エージェントを構築する

`triggers.json` の `command` から tmux 経由で Claude Code にメッセージを送るのが推奨パターン。Claude Code がメッセージの内容を理解し、適切に応答できる。

### 仕組み

```
チャットメッセージ → chat watch → trigger発火 → tmux send → Claude Code が処理
```

### Step 1: Claude Code を tmux で起動する

**ウィンドウ名にエージェント名を使う。** `agents:0` のようなインデックスではなく `agents:Opus` のように名前で指定できるため、管理しやすく、エージェントの追加・削除でインデックスがずれる心配もない。

```bash
tmux new-session -d -s agents -n Opus
tmux send-keys -t agents:Opus 'cd /path/to/project && claude' Enter
```

起動後、Claude Code の初期プロンプトでエージェントの役割を伝えておく:

```bash
S=~/.claude/skills/tmux/send.sh
bash $S --target agents:Opus "あなたはQQchatのエージェント「Opus」です。chat context --agent Opus でコンテキストを確認して。メッセージが届いたら chat unread --for Opus で確認し、適切に返信してください。返信は chat send <channel> 'msg' --agent-name Opus で送ってください。"
```

### Step 2: triggers.json を設定する

`.chat/triggers.json`:

```json
[
  {
    "name": "opus-agent",
    "pattern": "@Opus",
    "command": "bash ~/.claude/skills/tmux/send.sh --target agents:Opus 'QQchatで@Opusへのメンションがありました。chat unread --for Opus で未読を確認して返信してください。'",
    "cooldown": 30
  }
]
```

ポイント:
- `--target agents:Opus` は tmux セッション `agents` のウィンドウ `Opus` を指す
- ウィンドウ名 = エージェント名なので、対応関係が一目でわかる
- Claude Code はユーザー入力としてメッセージを受け取り、自動で処理を開始する
- cooldown で連投を防止する

### Step 3: chat watch を起動する

別のターミナル（または tmux の別ウィンドウ）で:

```bash
chat watch
```

### 複数エージェントの例

```bash
# エージェントごとにウィンドウ名をエージェント名にする
tmux new-session -d -s agents -n Opus
tmux send-keys -t agents:Opus 'cd /path/to/project && claude' Enter

tmux new-window -t agents -n Haiku
tmux send-keys -t agents:Haiku 'cd /path/to/project && claude' Enter
```

`.chat/triggers.json`:

```json
[
  {
    "name": "opus",
    "pattern": "@Opus",
    "command": "bash ~/.claude/skills/tmux/send.sh --target agents:Opus 'QQchatで@Opusへのメンションがありました。chat unread --for Opus で確認して返信してください。'",
    "cooldown": 30
  },
  {
    "name": "haiku",
    "pattern": "@Haiku",
    "command": "bash ~/.claude/skills/tmux/send.sh --target agents:Haiku 'QQchatで@Haikuへのメンションがありました。chat unread --for Haiku で確認して返信してください。'",
    "cooldown": 30
  }
]
```

ウィンドウ一覧で各エージェントの状態を確認できる:

```bash
tmux list-windows -t agents
# 0: Opus (1 panes) [active]
# 1: Haiku (1 panes)
```

### 全体の起動手順まとめ

```bash
# 1. サーバー起動（別ターミナル or tmux）
chat serve

# 2. エージェントを tmux ウィンドウで起動（ウィンドウ名 = エージェント名）
tmux new-session -d -s agents -n Opus
tmux send-keys -t agents:Opus 'cd /path/to/project && claude' Enter
bash ~/.claude/skills/tmux/send.sh --target agents:Opus "あなたはエージェント「Opus」です。..."

# 3. エージェント追加（必要に応じて）
tmux new-window -t agents -n Haiku
tmux send-keys -t agents:Haiku 'cd /path/to/project && claude' Enter
bash ~/.claude/skills/tmux/send.sh --target agents:Haiku "あなたはエージェント「Haiku」です。..."

# 4. chat watch 起動
chat watch
```

これで `@Opus` や `@Haiku` を含むメッセージがチャットに投稿されると、対応する Claude Code が自動的に未読を確認して返信する自律エージェントが完成する。