# Technical Documentation: openclaw/gogcli

> ℹ️ **Provenance:** Hybrid Fusion: `openclaw/gogcli` + `openclaw/docs` · [CodeWiki Reference](https://codewiki.google/github.com/openclaw/gogcli) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (openclaw/gogcli)

# gog 🧭 — Google Workspace from the terminal



[](https://github.com/openclaw/gogcli/actions/workflows/ci.yml)
[](https://github.com/openclaw/gogcli/releases/latest)
[](https://go.dev/)
[](LICENSE)
[](https://github.com/openclaw/homebrew-tap)

`gog` is one command-line client for Gmail, Calendar, Drive, Docs, Sheets, and
the wider Google Workspace surface. It is built for people, scripts, CI, and
agents that need explicit account routing, machine-readable output, and safety
controls.

```bash
gog --readonly gmail search 'is:unread newer_than:7d' --max 10 --json
gog --readonly calendar events --today --json
gog --readonly drive audit sharing --parent <folderId> --json
```

## Install

Homebrew is the shortest path on macOS and Linux:

```bash
brew install openclaw/tap/gogcli
gog --version
```

With Go:

```bash
go install github.com/openclaw/gogcli/cmd/gog@latest
gog --version
```

The module path moved from `github.com/steipete/gogcli` to
`github.com/openclaw/gogcli`. Until the first release tagged after that move is
published, `@latest` still selects an older tag that declares the previous path
and fails; install a specific version from the old path in the meantime:

```bash
go install github.com/steipete/gogcli/cmd/gog@v0.34.2
```

Docker images, Windows archives, raw macOS/Linux binaries, and source builds
are covered in the [install guide](docs/install.md).

## Quick start

Create a Desktop OAuth client in a [Google Cloud project](https://console.cloud.google.com/auth/clients),
download its JSON file, and authorize only the services you need:

```bash
gog auth credentials set ~/Downloads/client_secret_*.json
gog auth add you@gmail.com --services gmail,calendar,drive
export GOG_ACCOUNT=you@gmail.com
gog auth doctor --check
gog gmail search 'newer_than:7d' --max 10
```

The [five-minute quickstart](docs/quickstart.md) covers API enablement, the OAuth
consent screen, weekly-token-expiry avoidance, headless authorization, and
account defaults.

## Work with Google services

Commands follow the resource you are working with. These are the common entry
points; the [examples](docs/examples.md) and generated
[command index](docs/commands/README.md) cover the full surface.

| Work | Start with |
| --- | --- |
| Mail and calendars | `gog gmail search`, `gog calendar events` |
| Files and sharing | `gog drive ls`, `gog drive audit sharing` |
| Docs, Sheets, Slides, and Forms | `gog docs`, `gog sheets`, `gog slides`, `gog forms` |
| Contacts and tasks | `gog contacts`, `gog tasks` |
| Meetings and chat | `gog meet`, `gog chat`, `gog zoom` |
| Analytics and publishing | `gog analytics`, `gog searchconsole`, `gog youtube` |
| Workspace administration | `gog admin`, `gog groups`, `gog keep` |
| Discovery API fallback | `gog api describe`, `gog api call` |

Consumer Google accounts work with user-facing APIs. Admin Directory, Cloud
Identity Groups, Chat, Keep, and domain-wide delegation require a managed
Google Workspace domain. The [Workspace Admin guide](docs/workspace-admin.md)
explains that setup.

## Automate safely

`--json` emits structured output and `--plain` emits stable TSV. Prompts,
progress, and warnings go to stderr. `--no-input`, `--readonly`, exact command
allowlists, Gmail no-send policy, dry-run plans, and untrusted-content wrapping
let the caller define a narrower execution boundary.

```bash
gog --account you@gmail.com \
  --enable-commands-exact gmail.search,gmail.get \
  --gmail-no-send --readonly --no-input --wrap-untrusted --json \
  gmail search 'newer_than:7d'
```

See [Automation](docs/automation.md) for output and exit-code contracts, and
[Safety Profiles](docs/safety-profiles.md) for binaries with command policy and
locked flag values baked in at build time.

## Accounts and authentication

One installation can route among multiple Google accounts, named OAuth client
projects, direct access tokens, Application Default Credentials, and Workspace
service accounts. Tokens use the platform keyring by default; headless systems
can use the encrypted file backend.

```bash
gog auth list --check
gog auth alias set work you@company.com
gog --account work gmail search 'is:unread'
```

See [OAuth clients](docs/auth-clients.md) for client selection and service
accounts, and [Paths and State](docs/paths.md) for `GOG_HOME`, XDG paths, and
keyring storage.

## Discover the contract

The running binary generates its command schema, reference pages, and agent
skills from the same command tree:

```bash
gog schema --json
gog schema gmail search --json
gog help drive inventory
```

`gog mcp` exposes a typed stdio MCP server without a generic shell or command
bridge. It is read-only by default; writes require explicit command and tool
authorization. See the [MCP guide](docs/mcp.md).

## Supported OAuth services

The generated table below records the user OAuth and Workspace service-account
surface. `gog auth services` reports the same information from the installed
binary.


| Service | User | APIs | Scopes | Notes |
| --- | --- | --- | --- | --- |
| gmail | yes | Gmail API | `https://www.googleapis.com/auth/gmail.modify``https://www.googleapis.com/auth/gmail.settings.basic``https://www.googleapis.com/auth/gmail.settings.sharing` |  |
| calendar | yes | Calendar API | `https://www.googleapis.com/auth/calendar` |  |
| chat | yes | Chat API | `https://www.googleapis.com/auth/chat.spaces``https://www.googleapis.com/auth/chat.messages``https://www.googleapis.com/auth/chat.memberships``https://www.googleapis.com/auth/chat.users.readstate.readonly``https://www.googleapis.com/auth/chat.messages.reactions.create``https://www.googleapis.com/auth/chat.messages.reactions.readonly` |  |
| classroom | yes | Classroom API | `https://www.googleapis.com/auth/classroom.courses``https://www.googleapis.com/auth/classroom.rosters``https://www.googleapis.com/auth/classroom.coursework.students``https://www.googleapis.com/auth/classroom.coursework.me``https://www.googleapis.com/auth/classroom.courseworkmaterials``https://www.googleapis.com/auth/classroom.announcements``https://www.googleapis.com/auth/classroom.topics``https://www.googleapis.com/auth/classroom.guardianlinks.students``https://www.googleapis.com/auth/classroom.profile.emails``https://www.googleapis.com/auth/classroom.profile.photos` |  |
| drive | yes | Drive API | `https://www.googleapis.com/auth/drive` |  |
| driveactivity | yes | Drive Activity API | `https://www.googleapis.com/auth/drive.activity.readonly` | Read-only audit/activity scope; authorize with --services driveactivity |
| drivelabels | yes | Drive Labels API | `https://www.googleapis.com/auth/drive.labels.readonly` | Read-only Drive label schema; authorize with --services drivelabels |
| docs | yes | Docs API, Drive API | `https://www.googleapis.com/auth/drive``https://www.googleapis.com/auth/documents` | Export/copy/create via Drive |
| slides | yes | Slides API, Drive API | `https://www.googleapis.com/auth/drive``https://www.googleapis.com/auth/presentations` | Create/edit presentations |
| contacts | yes | People API | `https://www.googleapis.com/auth/contacts``https://www.googleapis.com/auth/contacts.other.readonly``https://www.googleapis.com/auth/directory.readonly` | Contacts + other contacts + directory |
| tasks | yes | Tasks API | `https://www.googleapis.com/auth/tasks` |  |
| sheets | yes | Sheets API, Drive API | `https://www.googleapis.com/auth/drive``https://www.googleapis.com/auth/spreadsheets` | Export via Drive |
| people | yes | People API | `profile` | OIDC profile scope |
| forms | yes | Forms API | `https://www.googleapis.com/auth/forms.body``https://www.googleapis.com/auth/forms.responses.readonly` |  |
| sites | yes | Drive API | `https://www.googleapis.com/auth/drive` | New Google Sites are exposed as Drive files |
| meet | yes | Meet REST API | `https://www.googleapis.com/auth/meetings.space.created``https://www.googleapis.com/auth/meetings.space.readonly``https://www.googleapis.com/auth/meetings.space.settings` |  |
| appscript | yes | Apps Script API | `https://www.googleapis.com/auth/script.projects``https://www.googleapis.com/auth/script.deployments``https://www.googleapis.com/auth/script.processes` |  |
| analytics | yes | Analytics Admin API, Analytics Data API | `https://www.googleapis.com/auth/analytics.readonly` | GA4 account summaries + reporting |
| searchconsole | yes | Search Console API | `https://www.googleapis.com/auth/webmasters` | Search Analytics + sitemap management |
| ads | yes | Google Ads API | `https://www.googleapis.com/auth/adwords` | OAuth scope only |
| groups | no | Cloud Identity API | `https://www.googleapis.com/auth/cloud-identity.groups.readonly` | Workspace only |
| keep | no | Keep API | `https://www.googleapis.com/auth/keep` | Workspace only; service account (domain-wide delegation) |
| admin | no | Admin SDK Directory API | `https://www.googleapis.com/auth/admin.directory.user``https://www.googleapis.com/auth/admin.directory.group``https://www.googleapis.com/auth/admin.directory.group.member` | Workspace only; service account with domain-wide delegation required |
| youtube | yes | YouTube Data API v3 | `https://www.googleapis.com/auth/youtube.readonly` | Most read operations also work with API key only (config youtube_api_key or GOG_YOUTUBE_API_KEY) |
| photos | yes | Photos Library API | `https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata` | Read-only app-created media only after Google Photos Library API scope changes |
| photospicker | no | Photos Picker API | `https://www.googleapis.com/auth/photospicker.mediaitems.readonly` | Consumer OAuth; explicit opt-in with --services photospicker; selected media only |


## Documentation

- [Overview and guides](https://gogcli.sh/)
- [Examples](docs/examples.md)
- [Command index](docs/commands/README.md)
- [Gmail workflows](docs/gmail-workflows.md)
- [Drive audits](docs/drive-audits.md)
- [Docs, Sheets, and Slides guides](docs/index.md#pick-your-path)
- [Changelog](CHANGELOG.md)

`gog` is open source and is not affiliated with Google.

## Credits

Inspired by Mario Zechner's [gmcli](https://github.com/badlogic/gmcli),
[gccli](https://github.com/badlogic/gccli), and
[gdcli](https://github.com/badlogic/gdcli).

## Development

The project requires the Go version declared in `go.mod`.

```bash
make build
make test
make ci
```

See [live testing](docs/live-testing.md) for opt-in Google API smoke tests and
[releasing](docs/RELEASING.md) for the maintainer workflow.

## License

[MIT](LICENSE)

## 2. Official Technical Reference & Guides (openclaw/docs)

## File: README.md

# openclaw-docs




Mirror repo for the published OpenClaw docs site.

Source of truth lives in [`openclaw/openclaw`](https://github.com/openclaw/openclaw), under `docs/`.

## How it works

1. English docs are authored in `openclaw/openclaw`.
2. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mirrors the docs tree into this repo.
3. This repo stores the published docs tree plus generated locale output.
4. `openclaw/docs/.github/workflows/translate-incremental.yml` debounces normal docs changes, while `translate-all.yml` handles full reconciliation for glossary changes, weekly schedule, release dispatch, or manual dispatch.
5. `.github/workflows/r2-pages.yml` builds the full unpruned static site and uploads changed objects to Cloudflare R2.
6. `.github/workflows/pages.yml` deploys the small Cloudflare Worker router that preserves clean URLs and markdown negotiation while reading docs from R2.

## Translation behavior

- Locale pages under `docs/<locale>/**` are generated output.
- Each translated page stores `x-i18n.source_hash`.
- The translate workflow computes a pending file list before calling the model.
- If no English source hashes changed, the workflow skips the expensive translation step entirely.
- If files changed, only the pending files are translated.
- The workflow retries transient model-format failures.
- Locale outputs are uploaded as artifacts first, then committed together by the finalizer.
- Incremental and full translation use separate concurrency lanes, so small docs edits do not cancel weekly or glossary-triggered full reconciliation.
- The weekly scheduled run uses full reconciliation mode to repair missed or flaky locale updates.

## Editing rules

- Do not treat this repo as the primary place for English doc edits.
- Make English doc changes in `openclaw/openclaw`, then let sync copy them here.
- Locale pages under `docs/<locale>/**` are generated output.
- `.openclaw-sync/source.json` records which `openclaw/openclaw` commit this mirror was synced from.

## Static site build

- `npm run docs:build` renders the mirrored Mintlify-flavored docs into `dist/docs-site`.
- `npm run docs:build:cloudflare` is the legacy Worker Static Assets fallback build.
- `npm run docs:build:r2` renders the full unpruned site and prepares `dist/docs-r2-manifest.json` for R2 upload.
- `npm run docs:r2:upload` uploads only changed R2 objects, reports cache hits/misses, and refuses to turn a broken remote manifest read into a full-tree reupload.
- Manual R2 refreshes audit objects before upload; unchanged objects remain cache hits, and transient HEAD failures fall back to the signed manifest. `R2_UPLOAD_PUT_ALL=1` is the emergency escape hatch for intentionally rewriting every object.
- `npm run docs:smoke` checks representative English and locale pages plus the Pagefind search bundle.
- `npm run docs:check` runs both steps.
- The generated site includes the language picker and static full-text search via Pagefind.
- Cloudflare deploys `workers/docs-router.ts`, which serves slashless page URLs, English markdown responses for `.md` paths or `Accept: text/markdown`, and `/api/search` through the `DOCS_BUCKET` R2 binding.
- Cloudflare hosting details and limitations are documented in `CLOUDFLARE.md`.

## Secrets

- `OPENCLAW_DOCS_SYNC_TOKEN` lives in `openclaw/openclaw` and lets the source repo push into this repo.
- `OPENCLAW_DOCS_I18N_OPENAI_API_KEY` lives in this repo and powers locale translation refreshes.
- `CLOUDFLARE_API_TOKEN` lives in this repo and deploys the `docs.openclaw.ai` router.
- R2 uploads verify `CLOUDFLARE_API_TOKEN`, try temporary R2 credentials, and normally fall back to the token-derived direct S3 credential form. `OPENCLAW_R2_ACCESS_KEY_ID` / `OPENCLAW_R2_SECRET_ACCESS_KEY` are only fallback upload credentials when the Cloudflare token cannot be verified.

---

## File: docs/index.md

---
summary: "OpenClaw is a multi-channel gateway for AI agents that runs on any OS."
read_when:
  - Introducing OpenClaw to newcomers
title: "OpenClaw"
---

# OpenClaw 🦞



> _"EXFOLIATE! EXFOLIATE!"_ — A space lobster, probably



<Columns>
  <Card title="Get Started" href="/start/getting-started" icon="rocket">
    Install OpenClaw and bring up the Gateway in minutes.
  </Card>
  <Card title="Run Onboarding" href="/start/wizard" icon="list-checks">
    Guided setup with `openclaw onboard` and pairing flows.
  </Card>
  <Card title="Connect a Channel" href="/channels" icon="message-circle">
    Link Discord, Signal, Telegram, WhatsApp, and more to chat from anywhere.
  </Card>
  <Card title="Open the Control UI" href="/web/control-ui" icon="layout-dashboard">
    Launch the browser dashboard for chat, config, and sessions.
  </Card>
</Columns>

## Browse docs

Mobile browsers may show the section menu without the full desktop tab bar. Use
these hub links to reach the same top-level docs areas from the page body.

<Columns>
  <Card title="Get started" href="/" icon="rocket">
    Overview, showcase, first steps, and setup guides.
  </Card>
  <Card title="Install" href="/install" icon="download">
    Install paths, updates, containers, hosting, and advanced setup.
  </Card>
  <Card title="Channels" href="/channels" icon="messages-square">
    Messaging channels, pairing, routing, access groups, and channel QA.
  </Card>
  <Card title="Agents" href="/concepts/architecture" icon="bot">
    Architecture, sessions, context, memory, and multi-agent routing.
  </Card>
  <Card title="Capabilities" href="/tools" icon="wand-sparkles">
    Tools, skills, cron, webhooks, and automation capabilities.
  </Card>
  <Card title="ClawHub" href="/clawhub" icon="store">
    Plugin marketplace, publishing, curation, and trust guidance.
  </Card>
  <Card title="Models" href="/providers" icon="brain">
    Providers, model configuration, failover, and local model services.
  </Card>
  <Card title="Platforms" href="/platforms" icon="monitor-smartphone">
    macOS, Windows, iOS, Android, nodes, and web surfaces.
  </Card>
  <Card title="Gateway & Ops" href="/gateway" icon="server">
    Gateway configuration, security, diagnostics, and operations.
  </Card>
  <Card title="Reference" href="/cli" icon="terminal">
    CLI reference, schemas, RPC, release notes, and templates.
  </Card>
  <Card title="Help" href="/help" icon="life-buoy">
    Troubleshooting, FAQs, testing, diagnostics, and environment checks.
  </Card>
</Columns>

## What is OpenClaw?

OpenClaw is a **self-hosted gateway** that connects your favorite chat apps — Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more via channel plugins — to AI coding agents. You run a single Gateway process on your own machine (or a server), and it becomes the bridge between your messaging apps and an always-available AI assistant.

**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service.

**What makes it different?**

- **Self-hosted**: runs on your hardware, your rules
- **Multi-channel**: one Gateway serves every configured channel plugin simultaneously
- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
- **Open source**: MIT licensed, community-driven

**What do you need?** Node 26 (recommended), or another supported release: Node 22.22.3+, Node 24.15+, or Node 25.9+. You also need an API key from your chosen provider and 5 minutes. For best quality and security, use the strongest latest-generation model available.

## How it works

```mermaid
flowchart LR
  A["Chat apps + plugins"] --> B["Gateway"]
  B --> C["OpenClaw agent"]
  B --> D["CLI"]
  B --> E["Web Control UI"]
  B --> F["macOS app"]
  B --> G["iOS and Android nodes"]
```

The Gateway is the single source of truth for sessions, routing, and channel connections.

## Key capabilities

<Columns>
  <Card title="Multi-channel gateway" icon="network" href="/channels">
    Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway process.
  </Card>
  <Card title="Plugin channels" icon="plug" href="/tools/plugin">
    Channel plugins add Matrix, Nostr, Twitch, Zalo, and more; official plugins install on demand.
  </Card>
  <Card title="Multi-agent routing" icon="route" href="/concepts/multi-agent">
    Isolated sessions per agent, workspace, or sender.
  </Card>
  <Card title="Media support" icon="image" href="/nodes/images">
    Send and receive images, audio, and documents.
  </Card>
  <Card title="Web Control UI" icon="monitor" href="/web/control-ui">
    Browser dashboard for chat, config, sessions, and nodes.
  </Card>
  <Card title="Mobile nodes" icon="smartphone" href="/nodes">
    Pair iOS and Android nodes for Canvas, camera, and voice-enabled workflows.
  </Card>
</Columns>

## Quick start

<Steps>
  <Step title="Install OpenClaw">
    On npm 12 or npm 11.16+:

    ```bash
    npm install openclaw@latest --allow-scripts=openclaw
    ```

    On npm 11.12 and earlier, omit `--allow-scripts=openclaw`. Upgrade npm
    11.13–11.15 before installing.

  </Step>
  <Step title="Onboard and install the service">
    ```bash
    openclaw onboard --install-daemon
    ```
  </Step>
  <Step title="Chat">
    Open the Control UI in your browser and send a message:

    ```bash
    openclaw dashboard
    ```

    Or connect a channel ([Telegram](/channels/telegram) is fastest) and chat from your phone.

  </Step>
</Steps>

Need the full install and dev setup? See [Getting Started](/start/getting-started).

## Dashboard

Open the browser Control UI after the Gateway starts.

- Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/)
- Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)



## Configuration (optional)

Config lives at `~/.openclaw/openclaw.json`.

- If you **do nothing**, OpenClaw uses the bundled OpenClaw agent runtime; DMs share the agent's main session, and each group chat gets its own session.
- If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules.

Example:

```json5
{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
}
```

## Start here

<Columns>
  <Card title="Docs hubs" href="/start/hubs" icon="book-open">
    All docs and guides, organized by use case.
  </Card>
  <Card title="Configuration" href="/gateway/configuration" icon="settings">
    Core Gateway settings, tokens, and provider config.
  </Card>
  <Card title="Remote access" href="/gateway/remote" icon="globe">
    SSH and tailnet access patterns.
  </Card>
  <Card title="Channels" href="/channels/telegram" icon="message-square">
    Channel-specific setup for Discord, Feishu, Microsoft Teams, Telegram, WhatsApp, and more.
  </Card>
  <Card title="Nodes" href="/nodes" icon="smartphone">
    iOS and Android nodes with pairing, Canvas, camera, and device actions.
  </Card>
  <Card title="Help" href="/help" icon="life-buoy">
    Common fixes and troubleshooting entry point.
  </Card>
</Columns>

## Learn more

<Columns>
  <Card title="Full feature list" href="/concepts/features" icon="list">
    Complete channel, routing, and media capabilities.
  </Card>
  <Card title="Multi-agent routing" href="/concepts/multi-agent" icon="route">
    Workspace isolation and per-agent sessions.
  </Card>
  <Card title="Security" href="/gateway/security" icon="shield">
    Tokens, allowlists, and safety controls.
  </Card>
  <Card title="Troubleshooting" href="/gateway/troubleshooting" icon="wrench">
    Gateway diagnostics and common errors.
  </Card>
  <Card title="About and credits" href="/reference/credits" icon="info">
    Project origins, contributors, and license.
  </Card>
</Columns>

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~5650 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/openclaw/gogcli