openclaw-git

Full Bitbucket Git workflow for OpenClaw — clone repos, manage branches, diff changes, stage, commit and push without leaving chat.

Tools provided

| Tool | Description | |------|-------------| | git_status | Working-tree status: branch, staged, modified, untracked | | git_clone | Clone a remote repo (supports shallow clones) | | git_checkout | Switch branch or create + checkout a new one | | git_branch | List local/remote branches | | git_diff | Unified diff (unstaged or staged, optionally scoped to a file) | | git_log | Recent commit history | | git_add | Stage files (or everything) | | git_commit | Create a commit from staged changes (attributed to the agent identity) | | git_push ⚠️ | Push branch to remote | | git_pull | Fetch + merge from remote | | git_fetch | Sync remote-tracking refs from a remote (never merges) | | git_stash | Push/pop/list stash | | git_reset ⚠️ | Move HEAD (soft / mixed / hard) | | git_worktree_add | Create a new worktree on a branch (new or existing) | | git_worktree_list | List all worktrees for a repo | | git_worktree_remove ⚠️ | Remove a worktree directory | | git_worktree_prune | Prune stale worktree administrative files |

Tools marked ⚠️ are optional and must be explicitly allowed in config.

Installation

# 1. Install the plugin
openclaw plugins install @kvasar/openclaw-git


# 2. Restart the gateway
openclaw gateway restart


# 3. Update the plugin
openclaw plugins update openclaw-git

Configuration

Bitbucket private repos

Generate an API token in Bitbucket:

1. Go to Bitbucket → Personal settings → API tokens
2. Click Create API token
3. Give it a label (e.g. openclaw-git)
4. Set scope: Repositories → Read (add Write if you want to push)
5. Copy the generated token

Then add to your OpenClaw config:

{
  "plugins": {
    "entries": {
      "openclaw-git": {
        "enabled": true,
        "config": {
          "bitbucketApiToken": "ATBBxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

How it works: Bitbucket API token auth uses the static username x-bitbucket-api-token-auth with your token as the password. You can either pass a clean Bitbucket HTTPS URL and let the plugin inject the token from config, or pass a fully credentialed URL directly. The token is injected ephemerally for each operation (through an insteadOf URL rewrite) and is never written to the repository's .git/config, and it is redacted from plugin responses.

git_push and git_pull also inject the configured token for Bitbucket HTTPS remotes. Any stale credentials already embedded in the remote URL are replaced with the configured token for that single operation, using an ephemeral -c url.<authenticated>.insteadOf=<original> rewrite — the token is never written to .git/config, and upstream tracking still points at the named remote (origin).

For SSH clones ([email protected]:...) no token is needed — your SSH key handles auth normally.

Optional tools allowlist

{
  "tools": {
    "allow": ["git_push", "git_reset", "git_clone"]
  }
}

Agent Git identity

Commits created through git_commit are attributed to the agent that created them, not to the human operator who happens to own the machine. The author and the committer are set together, so a commit is never half-attributed (author = agent, committer = human).

Identity is resolved per commit, in this order:

1. Explicit tool arguments — author_name / author_email passed to git_commit.
2. The OpenClaw agent identity — the name configured with openclaw agents set-identity (agents.entries.<id>.identity.name).
3. The plugin identity config — supplies the agent email (the OpenClaw identity schema defines name/theme/emoji/avatar but not email) and an optional name fallback.
4. Git configuration — used only when none of the above provides a value, so existing installations keep working unchanged.

The identity is applied with per-process GIT_AUTHOR_* / GIT_COMMITTER_* environment variables for a single Git invocation. The host's global (~/.gitconfig) and repository-local Git configuration are never modified, so several agents with different identities can safely share one machine.

Configure an agent identity

The agent name comes from the standard OpenClaw identity:

openclaw agents set-identity --agent clawbot --name "Clawbot"

Add the matching email (and, optionally, a name fallback or entries for other agents) to the plugin config:

{
  "plugins": {
    "entries": {
      "openclaw-git": {
        "config": {
          "identity": {
            "default": { "email": "[email protected]" },
            "agents": {
              "clawbot": { "name": "Clawbot", "email": "[email protected]" },
              "another-agent": { "name": "Another Agent", "email": "[email protected]" }
            }
          }
        }
      }
    }
  }
}

With this configuration and no explicit arguments, git_commit produces:

Author:    Clawbot <[email protected]>
Commit:    Clawbot <[email protected]>

Passing author_name / author_email to git_commit still wins over both the agent identity and the Git configuration.

Multiple agents on one host

Because identities are resolved per agent and applied per operation, running clawbot and another-agent side by side requires — and touches — no shared Git configuration. Each agent's commits are attributed to its own identity.

git_pull applies the same identity to any merge commit it creates. Other commit-producing operations (git_stash) intentionally keep the host Git behaviour.

Usage examples

Once installed, just ask the agent naturally:

Clone https://github.com/eclipse-edc/Connector into ~/projects/edc

Show me the status of ~/projects/my-app

Stage all changes in ~/projects/my-app and commit with message "fix: resolve NPE in auth filter"

Show me the diff of src/main/java/App.java before I stage it

Create a new branch feature/vc-policy and push it to origin

Pull the latest changes from main

Model Evaluation Matrix

| Model | Expected Performance | |---------|---------------------| | Claude Opus 4.8 | very High | | Claude Opus 4.7 | High | | GPT-5.5 | very High | | GPT-5.4 | High | | DeepSeek v4 Flash| High | | stepfun-ai/step-3.5-flash | Low | | stepfun-ai/step-3.7-flash | Medium | | z-ai/glm-5.1 | Medium |

git_fetch

Synchronise remote-tracking references without touching your working tree.

| Parameter | Type | Description | |-----------|------|-------------| | repo_path | string (required) | Path to the repository root. | | remote | string | Remote to fetch from (e.g. origin). Defaults to the repository's configured remote. | | refspec | string | Explicit refspec, e.g. main or refs/heads/*:refs/remotes/origin/*. | | prune | boolean | Remove remote-tracking refs that no longer exist on the remote (default false). | | tags | boolean | Also fetch all tags (default false). | | depth | number | Shallow fetch: limit history to this many commits. |

Returns a text summary: the remote fetched from, the refs added / updated / pruned (taken from git's own output) and — on failure — git's stderr, for example:

git fetch --prune nope failed: fatal: 'nope' does not appear to be a git repository

Authentication is not implemented by the plugin. Fetch uses whatever is already configured for the repository (SSH keys, credential helpers, insteadOf rewrites, ...). Authentication failures are surfaced as git's own error message.

Safety — git_fetch is a remote-read / synchronisation operation:

• it never modifies tracked working-tree files;
• it can add, update and prune remote-tracking refs under .git/refs/remotes and related repository metadata;
• it never runs git pull, merge or rebase implicitly — use git_pull when you actually want to integrate changes.

Example agent usage

Fetch the latest remote references in ~/projects/my-app before inspecting a remote branch.

git_fetch  repo_path="~/projects/my-app"  remote="origin"  prune=true

License

Brought with ❤️ by Kvasar Technologies

MIT © KVASAR Technologies