차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

--- ai:openclaw_agent_googlechat [2026-10-30 12:08] – DokuWiki 솔루션 이전; 공개 인증정보 정제. 기존 본문/목차 보존. migration
+++ ai:openclaw_agent_googlechat [2026-10-30 14:55] (현재) – 바깥 편집 127.0.0.1
@@ 줄 1: / 줄 1: @@
+====== 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. 새 에이전트 추가 흐름 (개요) =====
+새 에이전트를 추가할 때 기본 흐름은 다음과 같습니다.
+. **에이전트 ID/역할 정의**
+     * 예: `brand-helper`, `export-bot`, `analytics-bot` 등
+. **워크스페이스 준비**
+     * (옵션 A) 메인 workspace를 공유하면서, AGENTS.md/SOUL.md에 역할 섹션만 구분
+     * (옵션 B) 에이전트별 별도 workspace 디렉터리 생성 (권장: 역할이 많이 다를 때)
+. **OpenClaw config에 agent 블록 추가**
+     * 모델, workspace 경로, heartbeat, default 채널 라우팅 등을 정의
+. **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`
+실제 작업:
+. 서버에서 디렉터리 생성
+     * `mkdir -p ~/.openclaw/workspace-brand-strategy`
+. 최소 파일 세트 복사 (선택)
+     * 메인 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 앱 준비 ====
+. GCP 프로젝트 생성 후 **Google Chat API** 활성화
+. 서비스 계정 생성 → JSON Key 발급 → 서버에 저장
+. Google Chat 앱 구성
+     * 기능: Join spaces and group conversations
+     * 연결: HTTP endpoint URL → `https://<gateway>/googlechat`
+     * 트리거: 모든 트리거에 공통 HTTP endpoint 사용
+     * 가시성: 특정 사용자/그룹에만 노출
+. 앱 상태를 **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`에서만 사용 (실무상 "이 방은 브랜드 전략 봇"이라고 고정)
+에이전트 추가/변경 시에는:
+. 새 workspace 준비 (또는 기존 workspace에 역할 섹션 추가)
+. OpenClaw config에 `agents.<id>` 블록 추가/수정
+. `channels.googlechat.groups`에 해당 space를 allowlist로 추가
+. 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에 에이전트 인식시키기 ====
+) **수정된 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
+```
+) 또는, `config.get` 출력에 바로 패치하는 형태로 쓸 수도 있지만,
+   실무에서는 **항상 파일로 따로 편집 후 `config.apply`** 하는 방식을 권장합니다.
+) config를 적용하면 Gateway가 자동으로 재시작되고,
+   새 `agents.<id>` 설정이 반영됩니다. 이 시점부터는:
+  * 해당 에이전트 ID가 뜨는 세션들이 생성될 수 있고
+  * Google Chat에서 해당 Space로 메시지가 들어오면, 설정에 따라 에이전트를 사용하게 됩니다.
+> 참고: 이 문서에서는 실제 `config.apply` 실행 예시만 보여주고, 실제 적용 시점/방법은 담당자가 직접 판단해서 실행해야 합니다.
+==== 7.4 Gateway 상태 점검 ====
+config 적용 후 Gateway가 제대로 올라왔는지 확인하려면:
+```bash
+# Gateway 전체 상태 확인
+openclaw status
+# 로그를 보고 싶을 때 (선택)
+openclaw gateway logs
+```
+에러 없이 올라와 있고, Google Chat에서 봇에게 메시지를 보냈을 때 응답이 온다면
+새 에이전트/스페이스 설정이 정상적으로 인식된 것으로 판단할 수 있습니다.