이 문서는 OpenClaw에 새로운 에이전트를 추가하고, Google Chat에서 여러 스페이스(웹훅 역할)를 설정해 사용하는 방법을 정리한 내부용 메뉴얼입니다.
이 페이지는 실제 설정/코드가 아니라 구조·흐름·설정 포인트를 이해하기 위한 가이드입니다. 실제 값(토큰, URL, 서비스 계정 JSON 등)은 별도 보안 문서/환경변수로 관리합니다.
OpenClaw에서 “에이전트”는 다음 3가지를 합친 개념입니다.
현재 이 환경에서는 `~/.openclaw/workspace`가 메인 에이전트(홍길동)의 워크스페이스입니다.
Google Chat 쪽은 하나의 Chat 앱이 있고, OpenClaw 쪽에 하나의 웹훅 엔드포인트(/googlechat)로 들어옵니다.
여기서 “여러 개의 웹훅”은 실제로는 하나의 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 역할로 쓸지"를 **워크스페이스/프롬프트 레벨에서 구분하는 방식**으로 운용합니다.
여기서는 별도 역할용 에이전트 하나를 추가하는 시나리오를 기준으로 정리합니다.
예시: 브랜드 전략 문서 전용 에이전트
실제 작업:
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" },
},
},
} ```
포인트:
새 workspace(`workspace-brand-strategy`) 안에는 최소 아래 파일을 두는 것을 권장합니다.
세부 절차는 `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마다 개별 설정을 둘 수 있습니다.
```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",
}
},
},
},
} ```
포인트:
실제 운용 시에는:
하는 식으로 분리 운용합니다.
에이전트 추가/변경 시에는:
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>` 설정이 반영됩니다. 이 시점부터는:
참고: 이 문서에서는 실제 `config.apply` 실행 예시만 보여주고, 실제 적용 시점/방법은 담당자가 직접 판단해서 실행해야 합니다.
config 적용 후 Gateway가 제대로 올라왔는지 확인하려면:
```bash # Gateway 전체 상태 확인 openclaw status
# 로그를 보고 싶을 때 (선택) openclaw gateway logs ```
에러 없이 올라와 있고, Google Chat에서 봇에게 메시지를 보냈을 때 응답이 온다면 새 에이전트/스페이스 설정이 정상적으로 인식된 것으로 판단할 수 있습니다.