OpenClaw Google Workspace 教學

Windows WSL Docker Gws 教學

第一步 建立 Google Cloud Project

到 Google Cloud Console 建立一個新的 project。gws OAuth 需要 GCP project 作為前提。

注意：2026年3月3日起，Google Cloud 已開始強制執行兩步驟驗證

建立完成兩步驟驗證，進入專案頁面

按下「新增專案」

在左邊欄位中點選[API與服務>OAuth同意畫面]

進入OAuth總覽頁面，按下「開始」

這代表開始設定 Google 驗證平台，也就是 OAuth app 的基本資料

應用程式目標選擇外部

輸入完成電子郵件後，按下同意條款後建立專案

建立完成後，進入目標對象頁面

注意，不要點擊「發布應用程式」，先保持「測試」狀態

如果有多個測試對象，可以加入「測試使用者」

我增加一個的測試用的帳號，記得增加自己的帳號

如果沒加 Test users，後面 gws auth login 很容易直接被擋

到「用戶端」建立 OAuth Client，先進入「用戶端」頁面

Client 類型一定要選 Desktop app，不要選 Web application，選錯最常見就是後面出現 redirect_uri_mismatch

設定適當的用戶端名稱

會得到用戶端密碼

下載 client JSON

如果還在「OAuth用戶端已建立」畫面，可以直接按下「下載JSON」

如果已經退出了畫面，可以點擊名稱，進入指定用戶端頁面

按下右下的「下載」符號，即可取得JSON

接下來要把json放在openclaw的設置中

方法1，使用指令移動

使用指令，直接放在gws資料夾

1. 找到 Windows 下載檔

通常在：

C:\Users\你的Windows帳號\Downloads\

在 WSL 內對應是：

/mnt/c/Users/你的Windows帳號/Downloads/

2. 複製到 WSL 的 gws 設定目錄

mkdir -p ~/.config/gws
cp /mnt/c/Users/你的Windows帳號/Downloads/client_secret_*.json ~/.config/gws/client_secret.json

3. 確認

ls -la ~/.config/gws

你應該會看到：

client_secret.json

方法2 使用檔案總管直接移動

下載回來名稱為「client_secret_...json」將名稱更改為「client_secret.json」

開啟資料夾 \\wsl.localhost\Ubuntu\home\使用者名稱

手動建立資料夾.config\gws

將剛剛下載並改名的json檔案貼入到資料夾內

確認檔案在WSL是否可以讀取

ls -l ~/.config/gws/client_secret.json

在 WSL 終端機 執行這幾行：

export PATH="$HOME/.cargo/bin:$PATH"
hash -r
which gws
gws --version

如果這樣成功，再把它永久寫進 shell：

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
which gws
gws --version

在 WSL 主機完成 OAuth，產生真正可用的 credentials.json

你已經把 client_secret.json 放在正確位置了，也就是：

/home/cg/.config/gws/client_secret.json

所以接著只要：

ls -l ~/.config/gws/client_secret.json
gws auth login -s drive
mkdir -p ~/openclaw/secrets/gws
gws auth export --unmasked > ~/openclaw/secrets/gws/credentials.json
ls -lh ~/openclaw/secrets/gws/credentials.json

快速安裝 (進入docker容器強制安裝)

docker compose exec -u root openclaw-gateway bash

# 1) 確認 npm 全域安裝位置

echo "$NPM_CONFIG_PREFIX"

ls -la "$NPM_CONFIG_PREFIX/bin"

# 2) 把 gws 放到所有使用者都找得到的 PATH 位置

ln -sf "$NPM_CONFIG_PREFIX/bin/gws" /usr/local/bin/gws

hash -r

# 3) 確認 gws 可執行

which gws

gws --version

# 4) 下載 gws repo

git clone --depth=1 https://github.com/googleworkspace/cli.git /opt/gws-repo

# 5) 注意：skills 要放到 /home/node/.openclaw/skills，不是 /root/.openclaw/skills

mkdir -p /home/node/.openclaw/skills

ln -sfn /opt/gws-repo/skills/gws-shared   /home/node/.openclaw/skills/gws-shared

ln -sfn /opt/gws-repo/skills/gws-drive    /home/node/.openclaw/skills/gws-drive

ln -sfn /opt/gws-repo/skills/gws-gmail    /home/node/.openclaw/skills/gws-gmail

ln -sfn /opt/gws-repo/skills/gws-calendar /home/node/.openclaw/skills/gws-calendar

ln -sfn /opt/gws-repo/skills/gws-sheets   /home/node/.openclaw/skills/gws-sheets

# 6) 確認 skills 已建立

ls -la /home/node/.openclaw/skills/

exit

docker compose restart openclaw-gateway

驗證安裝

docker compose exec openclaw-gateway sh -lc 'which gws && gws --version'

docker compose exec openclaw-gateway sh -lc 'ls -1 /home/node/.openclaw/skills | grep "^gws-"'

如果這兩條有正常輸出，代表：

• gws CLI 已可用
• OpenClaw 應該已經看得到 gws skills

第一次 OAuth 登入（先只開 Drive）

先確認 client_secret.json 在位，再做登入

ls -l ~/.config/gws/client_secret.json

gws auth login -s drive

如果已看到 Google Drive 已勾選，直接按 Enter 即可

[x] 代表已經選取，圖中顯示2/2 selected

如果沒有選取，可以使用空白鍵切換

確認完畢後會出現網址，開啟網頁並取得授權

按下繼續，這是自己的APP，允許存取

設定完成

回到WSL，會顯示已經完成設定

Drive 通過後，擴充到其他服務

gws auth login -s drive,gmail,calendar,sheets

可以選擇存取Google硬碟、Google表單、Gmail、Google日曆與雲端平台

確認完成後按下Enter進行下一步

進入網址後，設定OAuth授權

設定完成後，可以關閉視窗，回到WSL

回到WSL，設定已經完成

匯出 credentials.json 給 Docker 用

這一步產生的是 credentials.json（不是 client_secret.json），這才是之後掛進容器的憑證

mkdir -p ~/openclaw/secrets/gws

gws auth export --unmasked > ~/openclaw/secrets/gws/credentials.json

ls -lh ~/openclaw/secrets/gws/credentials.json

接著進行測試，先確認終端是否有真的吃到gws設定

確認三件事：

WSL 端 gws 可執行

credentials.json 已存在

容器端有吃到 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

# WSL 端

which gws

gws --version

ls -lh ~/openclaw/secrets/gws/credentials.json

# Docker / OpenClaw 端

docker compose exec openclaw-gateway sh -lc 'which gws && gws --version'

docker compose exec openclaw-gateway sh -lc 'echo "$GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE"'

docker compose exec openclaw-gateway sh -lc 'ls -1 /home/node/.openclaw/skills | grep "^gws-"'

測試1- Drive 只讀測試

先確認讀取權限正常

docker compose exec openclaw-gateway sh -lc \

  'gws drive files list --params '\''{"pageSize": 5}'\'''

如果出現這個訊息，代表容器缺少gws，或是路徑沒有打入到docker容器中

'gws drive files list --params '\''{"pageSize": 5}'\''' sh: 1: gws: not found

解決方式如下

1.      建立一個docker-compose.override.yml，內容如下(全部貼入)

services:

  openclaw-gateway:

    environment:

      NPM_CONFIG_PREFIX: /home/node/.openclaw/.npm-global

      PLAYWRIGHT_BROWSERS_PATH: /opt/pw-browsers

      PATH: /home/node/.openclaw/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/home/node/.dotnet/tools

      GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /run/secrets/gws-credentials.json

      GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND: file

    volumes:

      - ${GWS_CREDENTIALS_FILE:-./secrets/gws/credentials.json}:/run/secrets/gws-credentials.json:ro

  openclaw-cli:

    environment:

      NPM_CONFIG_PREFIX: /home/node/.openclaw/.npm-global

      PLAYWRIGHT_BROWSERS_PATH: /opt/pw-browsers

      PATH: /home/node/.openclaw/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/home/node/.dotnet/tools

      GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /run/secrets/gws-credentials.json

      GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND: file

    volumes:

      - ${GWS_CREDENTIALS_FILE:-./secrets/gws/credentials.json}:/run/secrets/gws-credentials.json:ro

2.      在openclaw資料夾中使用記事本開啟.env

在最後面加入這一行

GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /run/secrets/gws-credentials.json

3.      重建容器

cd ~/openclaw

docker compose up -d --force-recreate

4.      在容器裡重新安裝 gws

docker compose exec -u root openclaw-gateway sh -lc '

echo "NPM_CONFIG_PREFIX=$NPM_CONFIG_PREFIX"

npm install -g @googleworkspace/[email protected]

which gws || ln -sf "$NPM_CONFIG_PREFIX/bin/gws" /usr/local/bin/gws

hash -r

which gws

gws --version

'

5.      然後立刻驗證這三條

docker compose exec openclaw-gateway sh -lc 'which gws && gws --version'

docker compose exec openclaw-gateway sh -lc 'echo "$GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE"'

docker compose exec openclaw-gateway sh -lc 'ls -l /run/secrets/gws-credentials.json'

第一條有 gws 路徑與版本

第二條輸出：/run/secrets/gws-credentials.json

第三條看得到檔案存在

再次驗證

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc 'which gws && gws --version'

如果三條都有訊息，再繼續測試1-Drive 只讀

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc \

  'gws drive files list --params '\''{"pageSize": 5}'\'''

第一次進入，可能會出現403，需要開啟權限，進入頁面中的網址，每一個專案的ID不同，需要自行複製網址後設置

按下啟用Google Drive API

確認開啟權限，重新測試，應該會看到雲端硬碟的檔案

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc \

  'gws drive files list --params '\''{"pageSize": 5}'\'''

測試2-建立 test.txt 並上傳到 Drive

先建立檔案：

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc \

  'printf "OpenClaw GWS upload test\ncreated_at=2026-03-13\n" > /tmp/gws-test.txt && ls -l /tmp/gws-test.txt'

再上傳：

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc \

  'gws drive +upload /tmp/gws-test.txt --name "openclaw-gws-test-2026-03-13.txt"'

開啟Google Drive時，可以看見剛剛建立的檔案” openclaw-gws-test-2026-03-13.txt”，代表串連成功了

下一個測試：建立明天的測試行事曆事件

docker compose \

  -f docker-compose.yml \

  exec openclaw-gateway sh -lc \

  'gws calendar events insert \

    --params '\''{"calendarId":"primary"}'\'' \

    --json '\''{

      "summary":"OpenClaw GWS 測試事件",

      "description":"這是一筆用來驗收 gws + OpenClaw 的測試事件",

      "start":{"dateTime":"2026-03-14T15:00:00+08:00","timeZone":"Asia/Taipei"},

      "end":{"dateTime":"2026-03-14T15:30:00+08:00","timeZone":"Asia/Taipei"}

    }'\'''

第一次使用時，也需要開啟權限，開啟訊息中的網址

啟用Google行事曆系統

重新測試

開啟Google行事曆，可以看到

代表成功建立行事曆了

接下來測試，由OpenClaw來的操控功能

建議先修改TOOLS.md，增加下列文字(不是覆蓋，是增加)，需要明確告訴openclaw他有什麼技能，避免他使用錯誤的方法

## Google Workspace（gws）

目前環境已安裝並設定好 Google Workspace 工具，已可透過 gws 存取：

- Google Drive：列檔、搜尋、上傳、刪除

- Google Calendar：列日曆、列事件、建立事件、刪除事件

- Gmail：列標籤、讀取基本信箱資訊

- Google Sheets / Docs：若對應 gws skills 已安裝，則可使用

強制使用規則：

- 當使用者提到 Google Drive、Google Calendar、Gmail、Google Sheets、Google Docs 時，必須優先使用 gws。

- 不可自行改用 Python google-auth、google-api-python-client、服務帳戶程式碼、自寫 OAuth 流程，除非使用者明確要求修改相關程式碼。

- 不可自行尋找或假設其他憑證路徑，例如：

  - ~/.config/google-credentials.json

  - ~/google-credentials.json

  - 任何未由目前環境明確提供的 Google 憑證檔

- 若 gws 可用，禁止改用臨時 Python 腳本或其他自建認證方式存取 Google Workspace。

- 若 gws 執行失敗，必須回報實際的 gws / 工具錯誤，不可自行切換到其他 Google 認證方法。

WebChat / openclaw-control-ui 特別規則：

- 在 WebChat / openclaw-control-ui 中，若目前環境已安裝 gws，應直接在當前執行環境使用 gws CLI。

- 不要先嘗試 sessions_spawn、thread=true、ACP 子 agent、thread bindings 來操作 Google Workspace，除非使用者明確要求這種流程。

- 若要確認 gws 是否可用，先直接執行：

  - which gws

  - gws --version

  - echo $GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

- 若上述檢查通過，再直接執行 gws 指令，不要先宣告「WebChat 不支援 Google Drive / Google Calendar 即時存取」。

操作規則：

- 探索、查詢、驗證狀態時，優先做 read-only 操作。

- 建立、上傳、刪除、修改等寫入操作時，嚴格依照使用者提供的內容執行。

- 若需求有歧義，先澄清，不可自行猜測。

- 若操作可能造成資料刪除、覆蓋、寄信、行程異動等風險，且使用者意圖不夠明確，應先確認。

- 寫入成功後，一律回傳資源 ID（例如 file id、event id）。

- 不可捏造 Google Workspace 結果；若工具失敗，必須明確說明。

建議回覆格式：

- Drive：檔名 + file id

- Calendar：事件標題 + 開始時間 + 結束時間 + 時區 + event id

- Gmail：簡潔摘要，避免冗長

- Sheets / Docs：文件標題 + 資源 id + 重要變更摘要

### 已驗證的 gws 指令格式

目前環境中，以下 gws 指令格式已驗證可用，應優先沿用，不要自行發明其他 CLI flags。

#### 1. 基本檢查

- 檢查 gws 是否可用：

  which gws

  gws --version

  echo $GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

#### 2. Google Drive（已驗證）

- 列出 Google Drive 前 5 個檔案：

  gws drive files list --params '{"pageSize": 5}'

- Drive 上傳測試（若目前環境已建立檔案）：

  gws drive +upload /tmp/gws-test.txt --name "openclaw-gws-test.txt"

#### 3. Google Calendar（已驗證）

- 建立 Google Calendar 測試事件：

  gws calendar events insert --params '{"calendarId":"primary"}' --json '{"summary":"OpenClaw GWS 測試事件","description":"這是一筆用來驗收 gws + OpenClaw 的測試事件","start":{"dateTime":"2026-03-14T15:00:00+08:00","timeZone":"Asia/Taipei"},"end":{"dateTime":"2026-03-14T15:30:00+08:00","timeZone":"Asia/Taipei"}}'

- 讀取 Calendar 清單：

  gws calendar calendarList list

#### 4. 匯出認證（WSL / 有瀏覽器的機器）

- 匯出認證：

  gws auth export --unmasked > ~/openclaw/secrets/gws/credentials.json

### gws 指令規則

- 不要自行猜測 --limit、--order-by、--fields 等 CLI flags，除非先查過當前版本的 gws --help 或官方 schema。

- 不要使用 gws upload 當作頂層命令；Google Drive 上傳請優先使用 drive 相關 helper 或正式 drive commands。

- 若不確定參數格式，先執行：

  - gws --help

  - gws drive --help

  - gws drive files --help

  - gws calendar --help

  - gws calendar events --help

### gws help 後續規則

- 若為了確認參數而先執行 gws --help / 子命令 --help，接下來必須繼續執行真正的目標命令。

- 不可只回傳 help 分析就停止。

- 若命令格式仍不確定，應明確回報「目前需要你確認哪個參數格式」，而不是停在 help。

- 對於已驗證成功的命令格式，優先直接執行，不要重複停在 help。

### Google Drive / Calendar 任務的具體行為

- 當使用者要求「列出雲端硬碟前幾個檔案」時，優先使用：

  gws drive files list --params '{"pageSize": N}'

- 當使用者要求「建立行事曆事件」時，應優先使用：

  gws calendar events insert

- 當使用者要求「確認事件是否建立成功」時，可先查 calendar list 或相關 events 查詢，再回傳標題、時間與 event id。

- 進行 Calendar 建立後，回覆中必須明確列出：

  - 事件標題

  - 開始時間

  - 結束時間

  - 時區

  - event id

- 進行 Drive 上傳後，回覆中必須明確列出：

  - 檔名

  - file id

建議重啟容器，確保可以抓到最新設置

docker compose restart openclaw-gateway

測試1.1

使用強約束提示先測試一次

請直接使用目前環境已安裝好的 gws CLI，不要使用 sessions_spawn、thread=true、ACP 子 agent、Python、google-auth、服務帳戶程式碼或自寫 OAuth。

先執行：

1. which gws

2. gws --version

3. echo $GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE

若以上正常，再執行：

gws drive files list --params '{"pageSize": 5}'

請回傳每一步的原始 stdout / stderr，最後再整理成簡短結論。

測試1.2 使用簡短句子詢問

使用gws工具幫我找到雲端硬碟的前五個檔案與ID

測試1.3 上傳檔案

幫我使用gws工具，建立test.txt文件後並上傳到google drive

測試2.1-建立Google行事曆

使用gws工具，建立一個明天的行事曆，名字為"OpenClaw測試"

確認行事曆建立完畢

測試2.2 查詢行事曆

幫我查詢明天的行程

若要跨重建容器保留 skills，正式版建議改用 Dockerfile

建立Dockerfile.gws

ARG BASE_IMAGE=openclaw

FROM ${BASE_IMAGE}

USER root

RUN set -eux; \

    if command -v apt-get >/dev/null 2>&1; then \

      apt-get update && \

      apt-get install -y --no-install-recommends git ca-certificates && \

      rm -rf /var/lib/apt/lists/*; \

    elif command -v apk >/dev/null 2>&1; then \

      apk add --no-cache git ca-certificates; \

    fi

# 安裝 gws，鎖版本

RUN npm install -g @googleworkspace/[email protected] && gws --version

# clone skills repo

RUN git clone --depth=1 https://github.com/googleworkspace/cli.git /opt/gws-repo

# bootstrap script：啟動時把 skills copy 到 bind mount 目錄

RUN printf '#!/bin/sh\nset -eu\nSKILLS_DIR="/home/node/.openclaw/skills"\nmkdir -p "$SKILLS_DIR"\nfor s in gws-shared gws-drive gws-gmail gws-calendar gws-sheets; do\n  [ ! -e "$SKILLS_DIR/$s" ] && cp -R "/opt/gws-repo/skills/$s" "$SKILLS_DIR/$s"\ndone\n' \

    > /usr/local/bin/openclaw-gws-bootstrap.sh && \

    chmod +x /usr/local/bin/openclaw-gws-bootstrap.sh

ENV GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

USER node

建立docker-compose.override.yml

services:

  openclaw-gateway:

    image: openclaw:gws

    build:

      context: .

      dockerfile: Dockerfile.gws

    environment:

      GH_TOKEN: ${GH_TOKEN}

      GITHUB_TOKEN: ${GITHUB_TOKEN}

      NPM_CONFIG_PREFIX: /home/node/.openclaw/.npm-global

      PLAYWRIGHT_BROWSERS_PATH: /opt/pw-browsers

      PATH: /home/node/.openclaw/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/home/node/.dotnet/tools

      GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /run/secrets/gws-credentials.json

      GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND: file

    volumes:

      - ${GWS_CREDENTIALS_FILE:-./secrets/gws/credentials.json}:/run/secrets/gws-credentials.json:ro

  openclaw-cli:

    image: openclaw:gws

    environment:

      GH_TOKEN: ${GH_TOKEN}

      GITHUB_TOKEN: ${GITHUB_TOKEN}

      NPM_CONFIG_PREFIX: /home/node/.openclaw/.npm-global

      PLAYWRIGHT_BROWSERS_PATH: /opt/pw-browsers

      PATH: /home/node/.openclaw/.npm-global/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:/home/node/.dotnet/tools

      GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /run/secrets/gws-credentials.json

      GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND: file

    volumes:

      - ${GWS_CREDENTIALS_FILE:-./secrets/gws/credentials.json}:/run/secrets/gws-credentials.json:ro

接著使用指令進行安裝(將gws打入docker容器中)

DOCKER_BUILDKIT=0 docker build --no-cache -f Dockerfile.gws -t openclaw:gws .