Tools
Gtw
By GitHub team workflow automation - an openclaw plugin session-based issue generation, git operations, and PR review coordination.
Install
openclaw plugins install ~/code/plugins/gtwConfiguration Example
{
"model": "github/gpt-4o",
"watchList": ["owner/repo1", "owner/repo2"],
"maxReviewRounds": 5
}README
# gtw — GitHub Team Workflow (OpenClaw Plugin)
> GitHub team workflow automation — session-based issue generation, git operations, and PR review coordination via slash command.
## Features
- **Session-based workflow** — Draft in `wip.json`, confirm when ready. No accidental API calls.
- **AI-assisted issue creation** — `/gtw new` reads the parent session history and auto-generates a structured issue draft (title + body) with no manual input required.
- **Git operations** — `fix`, `push`, and `pr` commands wrap standard git workflows.
- **Emoji review protocol** — eyes claim → checklist → approved/changes verdict.
- **GitHub CLI integration** — Uses `gh` for auth; no manual token config needed.
## Installation
```bash
openclaw plugins install ~/code/plugins/gtw -l --dangerously-force-unsafe-install
openclaw gateway restart
```
- `-l` (link mode): changes to the source directory take effect immediately without reinstalling.
- `--dangerously-force-unsafe-install`: the dangerous-code scanner flags `child_process` calls used to invoke `git`/`gh` CLI. These are intentional — gtw is a GitHub workflow tool that wraps these CLIs. Use this flag to skip the false-positive scan result.
- Gateway auto-reloads the plugin; `openclaw gateway restart` ensures a clean start.
## Usage
```
/gtw <command> [args]
```
### Setup
```
/gtw on <workdir> Set working directory (resolves git remote)
```
### Issue Management
```
/gtw new Read conversation history, auto-generate issue draft (title + body) via AI, save to wip.json
/gtw update #<id> Update issue draft
/gtw confirm Execute all pending operations (create issue/branch/PR)
/gtw issue List open issues
/gtw show #<id> Show issue details
/gtw poll List open issues and PRs
```
### Git Operations
```
/gtw fix <issue_id> Claim issue (add gtw/wip label), fetch issue, derive branch name, create branch,
inject directive to trigger subagent, subagent fixes automatically, creates
pendingCommit, requires /gtw confirm to push, then unclaims (removes label)
/gtw push Stage → auto-commit (conventional format) → generate commit draft → save as pendingCommit
(two-step: run /gtw confirm to actually push)
/gtw rebase [branch] Sync current branch with remote — 有分支名：fetch → checkout → rebase 远程分支
— 无分支名：git pull --rebase origin <当前分支>
/gtw pr [issue_id] Generate PR title/body via LLM from commit diff, save as pendingPr draft
— /gtw pr (no args): uses current branch; never reads wip.json
— /gtw pr <issue_id>: derives branch from issue title (same as /gtw fix)
If remote branch exists → checks out and hard-resets to it.
If local branch exists but remote missing → checks out and prompts to run /gtw push.
If neither exists → uses current branch.
(two-step: run /gtw confirm to actually create the PR)
```
### Review
```
/gtw review Claim earliest PR with gtw/ready label from watch list
/gtw review <pr> Claim/review specific PR in current repo
/gtw watch add <owner>/<repo> Add repo to watch list
/gtw watch rm <owner>/<repo> Remove repo from watch list
/gtw watch list Show watched repos
```
### Config
```
/gtw config Show current config and wip.json
/gtw model Show current AI model (gtw-specific or session default)
/gtw model <model> Set custom AI model (e.g. github/gpt-4o)
/gtw model off Clear custom model, use session default
/gtw login Interactive OAuth login (device code flow)
/gtw login --pat <token> Register a Personal Access Token directly
```
## Configuration
### Authentication
`gtw` supports multiple authentication methods:
**Method 1: Personal Access Token (PAT) - Recommended for CI**
**Option A: Direct PAT input**
```
/gtw login --pat ghp_your_token_here
```
Validates the token via GitHub API and caches it to `~/.gtw/token.json`.
**Option B: Environment variable**
```bash
export GITHUB_TOKEN=ghp_your_token_here
/gtw login --pat
```
Uses and validates `GITHUB_TOKEN`, then caches it.
**Option C: Cached PAT from previous login**
Automatically used if you previously ran `/gtw login --pat`.
Generate a PAT at: https://github.com/settings/tokens (requires `repo` and `workflow` scopes)
**Method 2: Interactive OAuth Login**
Use the device code flow for interactive login:
```
/gtw login
```
This will:
1. **If GITHUB_CLIENT_ID is set**: Use custom OAuth app with device code flow
2. **If GITHUB_CLIENT_ID is NOT set** (default): Fall back to `gh auth login` using GitHub CLI's built-in OAuth app
- Opens browser for device code authentication
- Caches the token from gh CLI for gtw use
- No need to configure client ID/secret manually
**Method 3: GitHub CLI Integration**
`gtw` automatically uses `gh` CLI token if available. Make sure `gh auth login` has been run with `repo` scope:
```bash
gh auth login --hostname github.com --scopes repo,workflow
gh auth status
```
**Token Priority:**
1. `GITHUB_TOKEN` environment variable (PAT)
2. Cached token in `~/.gtw/token.json` (PAT or OAuth)
3. `gh auth token` (validated before use)
Check auth status anytime:
```
/gtw config
```
### Configuration Items
`~/.gtw/config.json` stores gtw-specific settings:
```json
{
"model": "github/gpt-4o",
"watchList": ["owner/repo1", "owner/repo2"],
"maxReviewRounds": 5
}
```
| Field | Default | Description |
|-------|---------|-------------|
| `model` | session default | AI model used for issue/PR generation and review. Use `github/<model>` for Copilot models, `minimax/<model>` for MiniMax, etc. |
| `watchList` | `[]` | Watch list of repos scanned by `/gtw review` (no-arg) for `gtw/ready` PRs. |
| `maxReviewRounds` | `5` | Maximum review rounds before a PR is marked `gtw/stuck`. Set to `0` to disable. |
| `llmTimeoutSeconds` | `60` | Timeout in seconds for LLM API calls. If a request times out, it is retried once. If both attempts time out, a `TimeoutError` is thrown. Can be overridden with the `GTW_LLM_TIMEOUT_SECONDS` environment variable (takes precedence). |
View/edit via:
```
/gtw model <provider/model-id> # set custom AI model
/gtw model # show current model
/gtw model off # clear custom model
/gtw watch add <owner>/<repo> # add to watch list
/gtw watch list # show watch list
```
## Standard Workflow
```
You: /gtw on ~/code/myproject
→ ✅ Switched to owner/repo
📁 Workdir: /home/user/code/myproject
Let's discuss the requirements first — no code yet.
You: /gtw new
→ Draft saved:
Title: fix: handle null pointer in auth
Body:
## Background
...
## Acceptance Criteria
...
You: /gtw fix 42
→ 🌿 Fix workflow started
Issue: #42
Title: fix: handle null pointer in auth
Branch: fix/handle-null-pointer
⏳ Subagent spawned — the main session will now:
1. Spawn coding subagent to fix the issue
2. Wait for subagent to finish
3. Run push + confirm automatically
(gtw/wip label is applied to issue #42)
You: /gtw push
→ 🔍 Commit draft — run /gtw confirm to push
📝 Commit Message: fix(auth): handle null pointer in auth
📊 Changes: +10 -2
Run /gtw confirm to commit and push.
You: /gtw confirm
→ 📦 Committed and pushed
Branch: fix/handle-null-pointer
(gtw/wip label removed from issue #42)
You: /gtw pr
→ 🔍 PR draft — run /gtw confirm to create PR
📝 Title: fix: handle null pointer in auth
🌿 Branch: fix/handle-null-pointer → main
You: /gtw confirm
→ ✅ PR #42 created
URL: https://github.com/owner/repo/pull/42
```
### PR Workflow (with issue)
```
You: /gtw pr 13
→ 🔍 PR draft for issue #13 — run /gtw confirm to create PR
📝 Title: fix: handle null pointer in auth
🌿 Branch: fix/handle-null-pointer
⚠️ Remote branch missing — please run /gtw push to publish this branch
Issue: #13 — handle null pointer in auth
You: /gtw push
→ 🔍 Commit draft — run /gtw confirm to push
📝 Commit Message: fix(auth): handle null pointer in auth
Run /gtw confirm to commit and push.
You: /gtw confirm
→ 📦 Committed and pushed
Branch: fix/handle-null-pointer
You: /gtw pr 13
→ 🔍 PR draft for issue #13 — run /gtw confirm to create PR
📝 Title: fix: handle null pointer in auth
🌿 Branch: fix/handle-null-pointer → main
Issue: #13 — handle null pointer in auth
You: /gtw confirm
→ ✅ PR #42 created
URL: https://github.com/owner/repo/pull/42
```
### Review Workflow
```
You: /gtw watch add owner/repo
→ ✅ Now watching: owner/repo
You: /gtw review
→ eyes Claimed PR #23: fix: handle null pointer
Linked Issue: #12 — handle null pointer in auth
Files changed (3):
- src/auth.js: +10 -2
- tests/auth.test.js: +5 -0
Review [Round 1/5]
- [ ] Destructive
- [ ] Out-of-scope
Review the diff against the issue requirements.
Run /gtw review 23 again after resolving items.
You: /gtw review 23
→ eyes PR #23 re-review (Round 2/5)
[Items still unresolved kept as unchecked]
Review the diff and update checklist.
```
**Review protocol:**
- `/gtw review` (no-arg): Scans watch list for PRs labeled `gtw/ready`, picks the oldest by `updated_at`, claims it (`gtw/wip`), creates a Round 1 checklist.
- `/gtw review <pr>`: Reviews specific PR in the current repo (from `wip.json`). If a checklist exists, increments the round and updates the same comment.
- Checklist items (always two): **Destructive** and **Out-of-scope** — the canonical checks to prevent AI-caused unplanned or out-of-scope modifications.
- Each invocation increments the round number. Unresolved items remain unchecked.
- When all checkboxes are resolved (all items checked): checklist comment is deleted, approved comment posted, `gtw/lgtm` labe
... (truncated)
tools
Comments
Sign in to leave a comment