====== OpenClaw 에이전트 추가 + Google Chat 연동 가이드 ======

이 문서는 **OpenClaw에 새로운 에이전트를 추가**하고, **Google Chat에서 여러 스페이스(웹훅 역할)를 설정**해 사용하는 방법을 정리한 내부용 메뉴얼입니다.

> 이 페이지는 실제 설정/코드가 아니라 **구조·흐름·설정 포인트를 이해하기 위한 가이드**입니다. 실제 값(토큰, URL, 서비스 계정 JSON 등)은 별도 보안 문서/환경변수로 관리합니다.

-----

===== 1. 개념 정리 =====

==== 1.1 OpenClaw 에이전트 구조 ====  

OpenClaw에서 "에이전트"는 다음 3가지를 합친 개념입니다.

  * **workspace**: `~/.openclaw/workspace` (또는 별도 경로)
    * AGENTS.md, SOUL.md, MEMORY.md 등 텍스트 기반 운영 규칙/기억
  * **config 상의 agent 설정**: 기본 모델, 생각 모드, heartbeat, 채널 라우팅 설정
  * **세션 관리**: 각 채널(DM, 단톡방, Google Chat space 등)에 대한 대화 세션 JSONL

현재 이 환경에서는 `~/.openclaw/workspace`가 메인 에이전트(홍길동)의 워크스페이스입니다.

==== 1.2 Google Chat 채널 구조(요약) ====  

Google Chat 쪽은 하나의 **Chat 앱**이 있고, OpenClaw 쪽에 하나의 **웹훅 엔드포인트(/googlechat)**로 들어옵니다.

  * Google Chat 앱 → HTTP Webhook: `https://<gateway-domain>/googlechat`
  * OpenClaw `channels.googlechat` 설정으로 Chat API 서비스 계정/오디언스 등을 검증
  * 각 DM/Space는 `spaces/<id>`로 구분되고, config의 `groups` 블록에서 개별 설정 가능

여기서 "여러 개의 웹훅"은 **실제로는 하나의 HTTP 엔드포인트이지만, 여러 개의 Space(방)를 별도 설정으로 운용**하는 패턴으로 이해하면 됩니다.

-----

===== 2. 새 에이전트 추가 흐름 (개요) =====

새 에이전트를 추가할 때 기본 흐름은 다음과 같습니다.

  1. **에이전트 ID/역할 정의**
     * 예: `brand-helper`, `export-bot`, `analytics-bot` 등
  2. **워크스페이스 준비**
     * (옵션 A) 메인 workspace를 공유하면서, AGENTS.md/SOUL.md에 역할 섹션만 구분
     * (옵션 B) 에이전트별 별도 workspace 디렉터리 생성 (권장: 역할이 많이 다를 때)
  3. **OpenClaw config에 agent 블록 추가**
     * 모델, workspace 경로, heartbeat, default 채널 라우팅 등을 정의
  4. **Google Chat 라우팅에서 어느 space → 어느 agent를 쓸지 결정**
     * 실무상은 "이 space는 brand-helper 전용" 등으로 명시하고, systemPrompt/설명에 기록

※ 현재 버전 기준으로, Google Chat 설정 파일에서 space별로 agentId를 직접 매핑하는 공식 키는 없으므로, 
   "여러 agent를 돌리되 각 space에서 어떤 agent 역할로 쓸지"를 **워크스페이스/프롬프트 레벨에서 구분하는 방식**으로 운용합니다.

-----

===== 3. 에이전트 추가 – 실무 절차 =====

여기서는 **별도 역할용 에이전트 하나를 추가하는** 시나리오를 기준으로 정리합니다.

==== 3.1 에이전트 ID와 workspace 결정 ====

예시: **브랜드 전략 문서 전용 에이전트**

  * 에이전트 ID: `brand-strategy`
  * workspace 경로: `~/.openclaw/workspace-brand-strategy`

실제 작업:

  1. 서버에서 디렉터리 생성
     * `mkdir -p ~/.openclaw/workspace-brand-strategy`
  2. 최소 파일 세트 복사 (선택)
     * 메인 workspace의 `AGENTS.md`, `SOUL.md`, `TOOLS.md`를 참고용으로 복사 후, 
       새 에이전트에 맞게 내용 축소/편집

==== 3.2 새 에이전트용 config 블록 추가 ====

OpenClaw config(JSON5) 예시(개념용):

```json5
{
  agent: {
    // 메인 에이전트 기본값
    model: "openai/gpt-5.1-codex",
    workspace: "~/.openclaw/workspace",
  },
  agents: {
    brand-strategy: {
      model: "openai/gpt-5.1-codex",
      workspace: "~/.openclaw/workspace-brand-strategy",
      thinkingDefault: "low",
      heartbeat: { every: "0m" },
    },
  },
}
```

포인트:

  * `agent` 블록: 기본(메인) 에이전트 설정
  * `agents.<id>` 블록: 추가 에이전트별 override 설정
  * 실제 config 파일 위치/키 구조는 현재 서버의 `openclaw gateway config.get` 결과를 기준으로 맞춰야 합니다 (이 문서는 구조 예시).

==== 3.3 워크스페이스 내 문서 세팅(요약) ====

새 workspace(`workspace-brand-strategy`) 안에는 최소 아래 파일을 두는 것을 권장합니다.

  * `AGENTS.md` – 이 에이전트의 역할/책임/주의사항
  * `SOUL.md` – 말투/성향/제약사항
  * `TOOLS.md` – 이 에이전트가 사용할 수 있는 외부 도구/계정 메모

-----

===== 4. Google Chat 채널 기본 세팅 (요약) =====

세부 절차는 `docs/channels/googlechat.md` 기준이며, 여기서는 핵심만 정리합니다.

==== 4.1 Google Cloud / Chat 앱 준비 ====

  1. GCP 프로젝트 생성 후 **Google Chat API** 활성화
  2. 서비스 계정 생성 → JSON Key 발급 → 서버에 저장
  3. Google Chat 앱 구성
     * 기능: Join spaces and group conversations
     * 연결: HTTP endpoint URL → `https://<gateway>/googlechat`
     * 트리거: 모든 트리거에 공통 HTTP endpoint 사용
     * 가시성: 특정 사용자/그룹에만 노출
  4. 앱 상태를 **Live - available to users**로 전환

==== 4.2 OpenClaw config에서 googlechat 채널 활성화 ====

예시:

```json5
{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/googlechat-service-account.json",
      audienceType: "app-url",
      audience: "https://<gateway-domain>/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // 선택: 멘션 감지 개선용
      dm: {
        policy: "pairing",
        allowFrom: ["name@example.com"],
      },
      groupPolicy: "allowlist",
      groups: {
        // 아래 5.절에서 설명
      },
      mediaMaxMb: 20,
    },
  },
}
```

-----

===== 5. Google Chat 스페이스별 설정 (여러 "웹훅" 역할) =====

Google Chat은 HTTP 엔드포인트는 하나이지만, **각 스페이스(방) ID마다 개별 설정**을 둘 수 있습니다.

==== 5.1 스페이스 ID 확인 방법 ====

  * Google Chat에서 해당 방을 열고, 브라우저 주소창의 `spaces/AAAA...` 부분을 확인
  * 또는 OpenClaw 로그/메시지 payload에서 `space.name` 필드를 확인
    * 예: `spaces/AAAA1234567`

==== 5.2 config.groups 에 여러 스페이스 정의 예시 ====

```json5
{
  channels: {
    googlechat: {
      // ... (상동)
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA-brand": {
          allow: true,
          requireMention: true,
          users: ["name@example.com"],
          // brand-strategy 에이전트 전용 방으로 사용 (역할을 설명으로 기록)
          note: "브랜드 전략 문서/제품 표시 가이드 전용 Space",
        },
        "spaces/BBBB-export": {
          allow: true,
          requireMention: true,
          users: ["name@example.com"],
          note: "수출/해외영업 자료 전용 Space",
        }
      },
    },
  },
}
```

포인트:

  * 각각의 `spaces/...` 항목이 **사실상 “별도의 웹훅 엔트리”** 역할을 합니다.
  * 현재 버전 기준으로 config에서 space별로 agentId를 직접 지정하는 키는 공개되어 있지 않으므로,
    실제 운용 시에는:
    * 이 Space에서는 `brand-strategy` 역할로만 질문한다 (AGENTS.md/공지에 명시)
    * 필요 시 해당 Space에서만 사용하는 프롬프트/설명 문구를 고정
    하는 식으로 분리 운용합니다.

-----

===== 6. 실제 운용 패턴 (권장 예시) =====

  * **메인 에이전트(홍길동)**
    * workspace: `~/.openclaw/workspace`
    * 채널: 개인 DM, 회사 공용 방, 메인 Google Chat space 등
  * **보조 에이전트 예: brand-strategy**
    * workspace: `~/.openclaw/workspace-brand-strategy`
    * 주 역할: 제품 표시 가이드/안전기준/IR용 서술 정리 등
    * Google Chat: `spaces/AAAA-brand`에서만 사용 (실무상 "이 방은 브랜드 전략 봇"이라고 고정)

에이전트 추가/변경 시에는:

  1. 새 workspace 준비 (또는 기존 workspace에 역할 섹션 추가)
  2. OpenClaw config에 `agents.<id>` 블록 추가/수정
  3. `channels.googlechat.groups`에 해당 space를 allowlist로 추가
  4. Space 상단 공지 또는 위키에 "이 방은 어떤 역할의 에이전트와 상호작용하는 방인지"를 기입

이 문서는 구조/흐름 기준이며, 실제 JSON 경로·키 구조는 현재 서버의 OpenClaw config를 기준으로 맞추어야 합니다.

-----

===== 7. WSL 환경에서 실제로 입력할 명령어 정리 =====

이 환경은 **Windows + WSL2(Ubuntu)** 조합 기준입니다. 아래 예시는 WSL 터미널(예: `Ubuntu` 콘솔)에서 실행하는 것을 전제로 작성했습니다.

==== 7.1 새 에이전트용 workspace 디렉터리 만들기 ====

예시: `brand-strategy` 에이전트용 별도 워크스페이스

```bash
# 1) WSL 터미널에서 실행 (Ubuntu)
cd ~

# 2) 새 워크스페이스 디렉터리 생성
mkdir -p ~/.openclaw/workspace-brand-strategy

# 3) 메인 워크스페이스 일부 파일 참고용 복사 (선택)
cp ~/.openclaw/workspace/AGENTS.md ~/.openclaw/workspace-brand-strategy/AGENTS.md
cp ~/.openclaw/workspace/SOUL.md   ~/.openclaw/workspace-brand-strategy/SOUL.md
cp ~/.openclaw/workspace/TOOLS.md  ~/.openclaw/workspace-brand-strategy/TOOLS.md

# 이후 vi/nano/VSCode 등으로 파일 편집
#   vi ~/.openclaw/workspace-brand-strategy/AGENTS.md
```

==== 7.2 현재 OpenClaw config 확인하기 ====

OpenClaw가 WSL에서 돌아가는 경우, 보통 아래 명령으로 현재 Gateway 설정을 확인합니다.

```bash
# WSL 터미널에서
openclaw gateway config.get
```

출력 결과를 복사해서 안전한 편집기로 열고,
`agent` / `agents` / `channels.googlechat` 블럭 위치를 확인한 다음, 앞서 예시로 든 구조에 맞게 `agents.brand-strategy` 등을 추가합니다.

> 주의: config 수정은 **JSON5 문법 오류**가 나면 Gateway가 올라오지 않을 수 있으니,
> 콤마/따옴표/괄호를 특히 조심합니다.

==== 7.3 수정한 config 적용 + OpenClaw에 에이전트 인식시키기 ====

1) **수정된 config를 파일로 저장**했다고 가정할 때 (예: `/home/사용자/openclaw-config.json`):

```bash
# 1) 현재 config 백업 (선택)
openclaw gateway config.get > ~/openclaw-config-backup.json

# 2) 편집한 파일을 적용
openclaw gateway config.apply --file ~/openclaw-config.json
```

2) 또는, `config.get` 출력에 바로 패치하는 형태로 쓸 수도 있지만,
   실무에서는 **항상 파일로 따로 편집 후 `config.apply`** 하는 방식을 권장합니다.

3) config를 적용하면 Gateway가 자동으로 재시작되고,
   새 `agents.<id>` 설정이 반영됩니다. 이 시점부터는:

  * 해당 에이전트 ID가 뜨는 세션들이 생성될 수 있고
  * Google Chat에서 해당 Space로 메시지가 들어오면, 설정에 따라 에이전트를 사용하게 됩니다.

> 참고: 이 문서에서는 실제 `config.apply` 실행 예시만 보여주고, 실제 적용 시점/방법은 담당자가 직접 판단해서 실행해야 합니다.

==== 7.4 Gateway 상태 점검 ====

config 적용 후 Gateway가 제대로 올라왔는지 확인하려면:

```bash
# Gateway 전체 상태 확인
openclaw status

# 로그를 보고 싶을 때 (선택)
openclaw gateway logs
```

에러 없이 올라와 있고, Google Chat에서 봇에게 메시지를 보냈을 때 응답이 온다면
새 에이전트/스페이스 설정이 정상적으로 인식된 것으로 판단할 수 있습니다.