Skip to main content

Developer Setup

Local development environment setup for OpenClaw.

Quick Start (Scripts)​

Run both setup scripts to get going fast:

# 1. Install all macOS tools (Homebrew, 1Password CLI, git, gh, linters)
./scripts/setup-mac.sh

# 2. Configure the repo (remote, Dropbox ignore, hooks, branch tracking)
./scripts/setup-repo.sh

Both scripts are idempotent — safe to re-run anytime to verify or repair your setup.

Manual Steps (Reference)​

The sections below explain what the scripts do, step by step.

1. Install Homebrew (if needed)​

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install 1Password and CLI​

Install the 1Password desktop app, then install the CLI:

brew install --cask 1password-cli

Verify:

op --version
op account list  # should show your account

3. Set Up SSH Authentication with GitHub​

Follow the full guide in ssh-github-setup.md. The short version:

  1. Enable the SSH agent in 1Password (Settings → Developer → SSH Agent)

  2. Create or confirm an SSH key exists in 1Password (ed25519, Shared-Infrastructure vault)

  3. Register the key in ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.toml

  4. Configure ~/.ssh/config to use the 1Password agent:

    Host *
      IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

  5. Add GitHub's host key:

    ssh-keyscan github.com >> ~/.ssh/known_hosts

  6. Test:

    ssh -T git@github.com
    # Expected: Hi langhalsb! You've successfully authenticated...

4. Install Git and GitHub CLI​

brew install git gh

Configure git identity, authenticate gh via browser OAuth, and set SSH protocol:

git config --global user.name "Ben Langhals"
git config --global user.email "ben.langhals@iamconsult.net"
gh auth login --hostname github.com --git-protocol ssh --web

5. Clone the Repo into Dropbox​

cd ~/Library/CloudStorage/Dropbox
git init openclaw
cd openclaw
git remote add origin git@github.com:langhalsb/openclaw.git
git fetch origin
git branch -M main
git reset --mixed origin/main
git checkout -- .
git branch --set-upstream-to=origin/main main

6. Tell Dropbox to Ignore .git​

Dropbox syncing .git internals causes corruption and conflicts. Mark the folder ignored:

xattr -w com.dropbox.ignored 1 .git

Verify:

xattr -p com.dropbox.ignored .git
# Expected: 1

The .git folder will show a grey minus icon in Finder, confirming Dropbox is skipping it.

7. Install Node.js and Cloudflare Wrangler​

Node.js is required for Docusaurus and Wrangler. Wrangler is the Cloudflare CLI for managing Pages deployments.

brew install node
npm install -g wrangler

Authenticate Wrangler with your Cloudflare account:

wrangler login

This opens a browser window for OAuth. After authorizing, verify:

wrangler whoami

8. Install Linters and Task Runner​

brew install jq shellcheck markdownlint-cli2 just

9. Install Docusaurus (Documentation Site)​

The docs site lives in website/ and deploys to Cloudflare Pages automatically on push to main.

cd website && npm install

Local development:

just docs-dev    # Start dev server at http://localhost:3000
just docs-build  # Production build

The site generates llms.txt and llms-full.txt at build time for LLM consumption.

10. Task Runner (just)​

The project uses just as a task runner. Run just to see all available commands:

just            # List all commands
just setup      # Full setup (mac + repo + docs)
just lint       # Run all linters
just docs-dev   # Start docs dev server

Git Hooks​

The repo includes pre-commit hooks that lint staged .sh and .md files before each commit. To enable them:

git config core.hooksPath .githooks

This tells git to use the .githooks/ directory (committed to the repo) instead of .git/hooks/ (local only).

What the pre-commit hook checks​

  • Shell scripts (.sh): Runs shellcheck for common bugs, quoting issues, and portability problems
  • Markdown files (.md): Runs markdownlint-cli2 using .markdownlint.jsonc config

Skipping hooks​

If you need to bypass the hook for a specific commit:

git commit --no-verify -m "message"

Linter Configuration​

Markdown lint rules are configured in .markdownlint.jsonc:

  • MD013 (line length) — disabled, tables and URLs make strict line limits impractical
  • MD025 (single top-level heading) — disabled
  • MD040 (fenced code block language) — enabled, all code fences must specify a language
  • MD060 (table column style) — disabled, too noisy for compact tables
  • MD032 (blanks around lists) — disabled