openclaw에 Google 서비스 연결하기

gogcli는 Google 서비스를 터미널에서 다룰 수 있게 해주는 CLI입니다. CLI로 연결이 되면, openclaw와 연계가 쉽습니다.

Gmail 검색과 발송, Google Calendar 일정 조회와 생성, Drive 파일 조회와 업로드, Docs 문서 생성과 수정, Sheets 업데이트, Slides 생성까지 폭넓게 다룰 수 있습니다.

이 글에서는 특히 브라우저가 없는 Cloud 환경에서 gogcli를 설치하고, 원격 OAuth 방식으로 Google 계정을 연결하는 방법을 정리합니다.

왜 gogcli를 쓰는가

gogcli를 사용하면 다음과 같은 작업을 CLI에서 직접 처리할 수 있습니다.

• Gmail 검색, 발송, 라벨 조회
• Google Calendar 일정 조회, 생성, 수정
• Google Drive 파일 조회, 업로드, 공유
• Google Docs 생성, 편집, 내보내기
• Google Sheets 생성, 값 읽기와 쓰기
• Google Slides 생성

이 구성은 OpenClaw 같은 에이전트 환경뿐 아니라 일반적인 자동화 스크립트, cron 작업, 개인 비서형 워크플로우에도 그대로 활용할 수 있습니다.

---

1. GCP 설정, OAuth JSON 획득

gogcli를 쓰려면 먼저 Google Cloud Platform에서 OAuth client를 만들어야 합니다.

1-1. 프로젝트 생성

Google Cloud Console에서 프로젝트를 하나 만듭니다.

• https://console.cloud.google.com/projectcreate

1-2. 필요한 API 활성화

이번 구성에서는 아래 API를 활성화했습니다.

• Gmail API
• Google Calendar API
• Google Drive API
• Google Docs API
• Google Sheets API
• Google Slides API

1-3. OAuth consent screen 설정

OAuth 동의 화면을 설정합니다.

• 앱 이름 입력
• 사용자 지원 이메일 지정
• Testing 상태라면 테스트 사용자 추가

1-4. OAuth Client 생성

OAuth 클라이언트는 Desktop app 타입으로 생성했습니다.

생성 후 JSON 파일을 다운로드하면 대략 이런 구조입니다.

{
  "installed": {
    "client_id": "xxx.apps.googleusercontent.com",
    "project_id": "your-project-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "xxxx",
    "redirect_uris": [
      "http://localhost"
    ]
  }
}

이 JSON이 이후 gogcli의 OAuth credentials로 사용됩니다.

---

2. Cloud에 Go 설치

설치 당시 Cloud에서는 make, git은 있었지만 go가 없어서 빌드가 실패했습니다.
또 gogcli는 특정 Go 버전을 요구했기 때문에, 배포판 기본 패키지보다 공식 Go tarball 설치가 더 안전했습니다.

예시:

cd /tmp
curl -LO https://go.dev/dl/go1.26.2.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.26.2.linux-amd64.tar.gz
printf '%s\n' 'export PATH=/usr/local/go/bin:$PATH' > /etc/profile.d/go.sh
chmod 644 /etc/profile.d/go.sh
export PATH=/usr/local/go/bin:$PATH
go version

정상 설치되면:

go version go1.26.2 linux/amd64

---

3. gogcli 설치

이제 gogcli를 소스에서 빌드합니다.

git clone https://github.com/steipete/gogcli.git /opt/gogcli
cd /opt/gogcli
make
./bin/gog --version

설치가 잘 되면 도움말도 확인할 수 있습니다.

./bin/gog --help

---

4. OAuth JSON 설치

앞에서 받은 GCP OAuth JSON을 Cloud에 올린 뒤, gogcli에 등록합니다.

예를 들어:

./bin/gog auth credentials set /path/to/client_secret.json
./bin/gog auth credentials list --plain

등록이 잘 되면 credentials 경로와 client 정보가 보입니다.

---

5. personal client를 사용하는 이유

가장 중요한 포인트는 default client와 분리하는 것이었습니다.

먼저 환경 변수를 고정합니다.

export GOG_CLIENT=personal
export GOG_ACCOUNT=your-email@gmail.com

또는 .bashrc에 추가합니다.

echo 'export GOG_CLIENT=personal' >> ~/.bashrc
echo 'export GOG_ACCOUNT=your-email@gmail.com' >> ~/.bashrc
source ~/.bashrc

이렇게 하지 않으면 예전에 생성된 default token과 새 token이 섞이면서 invalid_grant 문제가 발생할 수 있었습니다.

---

6. Manual OAuth 방식

Cloud/VPS에서는 --manual 방식이 가장 단순했습니다.

gog --client personal auth add your-email@gmail.com \
  --services gmail,calendar,drive,docs,sheets,slides \
  --manual

그러면 승인 URL이 출력됩니다.

Visit this URL to authorize:
https://accounts.google.com/o/oauth2/auth?...

이 URL을 로컬 PC 브라우저에서 열어 승인합니다.

승인이 끝나면 브라우저는 localhost callback 주소로 이동하려고 하는데, 실제로 페이지가 열릴 필요는 없습니다.

브라우저 주소창의 redirect URL 전체를 복사해서 VPS 터미널에 붙여 넣습니다.

예:

http://127.0.0.1:44071/oauth2/callback?state=...&code=...

정상 완료되면 아래처럼 출력됩니다.

email   your-email@gmail.com
services        calendar,docs,drive,gmail,sheets,slides
client  personal

---

7. 인증 확인

다음 명령으로 인증 상태를 확인합니다.

gog --client personal auth list --check

정상 상태는 다음과 같습니다.

your-email@gmail.com personal calendar,docs,drive,gmail,sheets,slides ... true oauth

---

8. 실제로 가장 많이 발생한 문제: stale token

토큰 목록을 확인합니다.

gog --client personal auth tokens list

문제가 있는 경우:

token:default:your-email@gmail.com
token:personal:your-email@gmail.com

이 경우 오래된 default token을 삭제합니다.

gog --client default auth tokens delete your-email@gmail.com

정상 상태:

token:personal:your-email@gmail.com

이 문제를 해결하지 않으면 아래 같은 오류가 계속 발생할 수 있었습니다.

refresh access token: oauth2: "invalid_grant" "Token has been expired or revoked."

실제로는 OAuth 승인 실패가 아니라, 오래된 token bucket이 남아 있어서 발생하는 문제였습니다.