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

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

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

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

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

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(방)를 별도 설정으로 운용하는 패턴으로 이해하면 됩니다.

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

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 역할로 쓸지"를 **워크스페이스/프롬프트 레벨에서 구분하는 방식**으로 운용합니다.

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

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

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

실제 작업:

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

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` 결과를 기준으로 맞춰야 합니다 (이 문서는 구조 예시).

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

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

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

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**로 전환

예시:

```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,
  },
},

} ```

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

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

```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에서만 사용하는 프롬프트/설명 문구를 고정

하는 식으로 분리 운용합니다.

• 메인 에이전트(홍길동)
  • 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를 기준으로 맞추어야 합니다.

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

예시: `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 ```

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

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

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

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

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` 실행 예시만 보여주고, 실제 적용 시점/방법은 담당자가 직접 판단해서 실행해야 합니다.

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

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

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

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