Skip to content

Commit 2c5afcc

Browse files
committed
docs(readme): trim defaults, add credential backends, fix requirements
- Drop proxy settings that match defaults from quick start config - Add Credential Backends table (pass, 1Password, Bitwarden, Keychain, age, env) - Add macOS launchd instructions alongside systemd - Fix Go version 1.21 → 1.24 to match go.mod - Mark sandbox tools as optional in requirements - Generalize diagram and prerequisites to not assume pass/firejail
1 parent 10aa3db commit 2c5afcc

1 file changed

Lines changed: 33 additions & 24 deletions

File tree

README.md

Lines changed: 33 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ You can also block dangerous commands server-side — the agent can `gh repo lis
4141

4242
```
4343
┌─────────────────────────────────────────────────────────┐
44-
│ SANDBOX (firejail)
44+
│ SANDBOX
4545
│ │
4646
│ agent calls "gh repo list" │
4747
│ ↓ │
@@ -58,7 +58,7 @@ You can also block dangerous commands server-side — the agent can `gh repo lis
5858
│ claw-wrap daemon (outside sandbox) │
5959
│ 1. Verifies HMAC signature + timestamp │
6060
│ 2. Checks args against blocked patterns │
61-
│ 3. Fetches GH_TOKEN from pass (password store)
61+
│ 3. Fetches GH_TOKEN from credential backend
6262
│ 4. Spawns real gh binary with token in environment │
6363
│ 5. Streams stdout/stderr back through socket │
6464
│ │
@@ -93,8 +93,8 @@ This example sets up `gh` (GitHub CLI) as a proxied tool.
9393

9494
### Prerequisites
9595

96-
- Linux with systemd
97-
- [pass](https://www.passwordstore.org/) (password store) with GPG configured
96+
- Linux with systemd or macOS with launchd
97+
- A credential backend — [pass](https://www.passwordstore.org/), 1Password CLI, Bitwarden CLI, macOS Keychain, or age
9898
- `gh` installed somewhere (e.g. via Homebrew: `brew install gh`)
9999

100100
### 1. Install claw-wrap
@@ -128,20 +128,6 @@ pass insert cli/github/token
128128
Create `/etc/openclaw/wrappers.yaml`:
129129

130130
```yaml
131-
proxy:
132-
timeout: 300s
133-
inline_threshold: 1MB
134-
hmac_secret_file: /run/openclaw/auth
135-
max_connections: 64
136-
read_header_timeout: 3s
137-
read_message_timeout: 15s
138-
max_stdin_message_size: 1MB
139-
replay_cache_ttl: 2m
140-
replay_cache_max_entries: 10000
141-
credential_cache_ttl: 0s
142-
max_output_size: 100MB
143-
max_connection_lifetime: 30m
144-
145131
credentials:
146132
github-token:
147133
source: pass:cli/github/token
@@ -153,8 +139,12 @@ tools:
153139
GH_TOKEN: github-token
154140
```
155141
142+
See [Configuration Reference](docs/CONFIG.md) for proxy tuning, output limits, and connection settings.
143+
156144
### 4. Start the daemon
157145
146+
**Linux (systemd):**
147+
158148
```bash
159149
sudo cp init/claw-wrap.service /etc/systemd/system/
160150
# Edit User=YOUR_USERNAME to your actual username
@@ -163,14 +153,21 @@ sudo systemctl daemon-reload
163153
sudo systemctl enable --now claw-wrap
164154
```
165155

156+
**macOS (launchd):**
157+
158+
```bash
159+
cp init/com.openclaw.claw-wrap.plist ~/Library/LaunchAgents/
160+
launchctl load ~/Library/LaunchAgents/com.openclaw.claw-wrap.plist
161+
```
162+
166163
### 5. Create the symlink
167164

168165
```bash
169166
claw-wrap install
170167
```
171168

172169
This creates symlinks in `/usr/local/bin` pointing to the auto-detected `claw-wrap` binary
173-
(auto-elevates with sudo if needed). Override the symlink directory with `--install-dir`:
170+
(auto-elevates with sudo if needed). Override with `--install-dir /other/path`.
174171

175172
### 6. Verify
176173

@@ -180,6 +177,19 @@ claw-wrap check # Should show credentials OK (run from host/admin context)
180177
gh repo list # Should work — using proxied credentials
181178
```
182179

180+
## Credential Backends
181+
182+
| Backend | Format | Example |
183+
| --- | --- | --- |
184+
| [pass](https://www.passwordstore.org/) | `pass:path` | `pass:cli/github/token` |
185+
| [1Password CLI](https://developer.1password.com/docs/cli/) | `op://vault/item/field` | `op://dev/github/token` |
186+
| [Bitwarden CLI](https://bitwarden.com/help/cli/) | `bw:item-uuid` | `bw:a1b2c3d4` |
187+
| macOS Keychain | `keychain:service` | `keychain:github-token` |
188+
| [age](https://age-encryption.org/) | `age:/path/file.age` | `age:/etc/secrets/token.age` |
189+
| Environment | `env:VAR` | `env:GH_TOKEN` |
190+
191+
All backends support `| .jq_expr` suffix for JSON field extraction (e.g. `op://vault/item/field | .token`).
192+
183193
## Safety Controls
184194

185195
claw-wrap doesn't just proxy credentials — it enforces what the agent can do with them.
@@ -351,11 +361,10 @@ make clean # Remove build artifacts
351361

352362
## Requirements
353363

354-
- Go 1.21+ (building from source)
355-
- Linux with systemd (or macOS with launchd)
356-
- `pass` (password-store) + GPG
357-
- [firejail](https://firejail.wordpress.com/) (Linux) or [nono](https://github.com/lukehinds/nono)
358-
(macOS)
364+
- Go 1.24+ (building from source)
365+
- Linux with systemd or macOS with launchd
366+
- A supported credential backend (see [table above](#credential-backends))
367+
- Optional: [firejail](https://firejail.wordpress.com/) (Linux) or [nono](https://github.com/lukehinds/nono) (macOS) for sandbox isolation
359368

360369
## License
361370

0 commit comments

Comments
 (0)