From 8c9e41aab421cea12711a16b829ce926ce0336d5 Mon Sep 17 00:00:00 2001 From: bellman Date: Fri, 15 May 2026 10:43:35 +0900 Subject: [PATCH] omx(team): auto-checkpoint worker-3 [unknown] --- README.md | 5 +- USAGE.md | 28 ++++- docs/windows-install-release.md | 192 ++++++++++++++++++++++++++++++++ 3 files changed, 223 insertions(+), 2 deletions(-) create mode 100644 docs/windows-install-release.md diff --git a/README.md b/README.md index 3a26301d..f624390e 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Claw Code is the public Rust implementation of the `claw` CLI agent harness. The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**. > [!IMPORTANT] -> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. +> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Windows users can jump to the PowerShell-first [Windows install and release quickstart](./docs/windows-install-release.md). Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. > > **ACP / Zed status:** `claw-code` does not ship an ACP/Zed daemon entrypoint yet. Run `claw acp` (or `claw --acp`) for the current status instead of guessing from source layout; `claw acp serve` is currently a discoverability alias only, and real ACP support remains tracked separately in `ROADMAP.md`. @@ -96,6 +96,8 @@ export ANTHROPIC_API_KEY="sk-ant-..." .\target\debug\claw.exe prompt "say hello" ``` +For release ZIPs, PATH setup, provider switching, and notification smoke checks, see [`docs/windows-install-release.md`](./docs/windows-install-release.md). + **Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install. ## Post-build: locate the binary and verify @@ -188,6 +190,7 @@ cargo test --workspace ## Documentation map - [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness +- [`docs/windows-install-release.md`](./docs/windows-install-release.md) — PowerShell-first install, release artifact, provider switching, and Windows/WSL notification smoke paths - [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout - [`PARITY.md`](./PARITY.md) — parity status for the Rust port - [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details diff --git a/USAGE.md b/USAGE.md index 5e9a41cf..acc892f9 100644 --- a/USAGE.md +++ b/USAGE.md @@ -31,7 +31,7 @@ cd rust cargo build --workspace ``` -The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step. +The CLI binary is available at `rust/target/debug/claw` after a debug build (`rust\target\debug\claw.exe` on Windows). Make the doctor check above your first post-build step. For PowerShell-first install, release ZIP, PATH, provider-switching, and Windows/WSL notification examples, see [`docs/windows-install-release.md`](./docs/windows-install-release.md). ## Quick start @@ -230,6 +230,32 @@ export ANTHROPIC_AUTH_TOKEN="anthropic-oauth-or-proxy-bearer-token" **If you meant a different provider:** if `claw` reports missing Anthropic credentials but you already have `OPENAI_API_KEY`, `XAI_API_KEY`, or `DASHSCOPE_API_KEY` exported, you most likely forgot to prefix the model name with the provider's routing prefix. Use `--model openai/gpt-4.1-mini` (OpenAI-compat / OpenRouter / Ollama), `--model grok` (xAI), or `--model qwen-plus` (DashScope) and the prefix router will select the right backend regardless of the ambient credentials. The error message now includes a hint that names the detected env var. + +### Windows PowerShell provider switching + +The same provider rules work in PowerShell. Use placeholder values in docs and tests; put real keys only in your private environment. Remove unrelated provider env vars when validating a switch so failures are easy to diagnose. + +```powershell +# Anthropic direct +$env:ANTHROPIC_API_KEY = "sk-ant-REPLACE_ME" +Remove-Item Env:\OPENAI_BASE_URL -ErrorAction SilentlyContinue +Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue +.\target\debug\claw.exe --model "sonnet" prompt "reply with ready" + +# OpenAI-compatible gateway / OpenRouter +Remove-Item Env:\ANTHROPIC_API_KEY -ErrorAction SilentlyContinue +$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1" +$env:OPENAI_API_KEY = "sk-or-v1-REPLACE_ME" +.\target\debug\claw.exe --model "openai/gpt-4.1-mini" prompt "reply with ready" + +# Local OpenAI-compatible server +$env:OPENAI_BASE_URL = "http://127.0.0.1:11434/v1" +Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue +.\target\debug\claw.exe --model "llama3.2" prompt "reply with ready" +``` + +See the full [Windows install and release quickstart](./docs/windows-install-release.md) for release artifact setup, persistent `setx` usage, and WSL notes. + ## Local Models `claw` can talk to local servers and provider gateways through either Anthropic-compatible or OpenAI-compatible endpoints. Use `ANTHROPIC_BASE_URL` with `ANTHROPIC_AUTH_TOKEN` for Anthropic-compatible services, or `OPENAI_BASE_URL` with `OPENAI_API_KEY` for OpenAI-compatible services. diff --git a/docs/windows-install-release.md b/docs/windows-install-release.md new file mode 100644 index 00000000..ce6ea606 --- /dev/null +++ b/docs/windows-install-release.md @@ -0,0 +1,192 @@ +# Windows install and release quickstart + +This page is the PowerShell-first path for installing, verifying, and safely switching providers on Windows. It is intentionally copyable without embedding live secrets. + +## Choose an install path + +### Option A: build from source in PowerShell + +Use this when you are developing Claw Code or testing a local checkout. + +```powershell +git clone https://github.com/ultraworkers/claw-code +Set-Location .\claw-code\rust +cargo build --workspace +.\target\debug\claw.exe --help +.\target\debug\claw.exe doctor +``` + +For an optimized local binary: + +```powershell +Set-Location .\claw-code\rust +cargo build --workspace --release +.\target\release\claw.exe --help +``` + +### Option B: use a release artifact + +Use this when a GitHub release publishes a Windows artifact. The exact asset name may include the version and architecture; prefer the `windows-x86_64` / `pc-windows-msvc` ZIP when available. + +```powershell +$Version = "vX.Y.Z" +$Asset = "claw-$Version-x86_64-pc-windows-msvc.zip" +$InstallRoot = "$env:LOCALAPPDATA\Programs\claw" +New-Item -ItemType Directory -Force $InstallRoot | Out-Null + +# Download the asset from the release page, then expand it: +Expand-Archive -Path ".\$Asset" -DestinationPath $InstallRoot -Force +& "$InstallRoot\claw.exe" --help +& "$InstallRoot\claw.exe" doctor +``` + +To make that binary available in new PowerShell windows: + +```powershell +$InstallRoot = "$env:LOCALAPPDATA\Programs\claw" +[Environment]::SetEnvironmentVariable( + "Path", + [Environment]::GetEnvironmentVariable("Path", "User") + ";$InstallRoot", + "User" +) +``` + +Open a new terminal before running `claw --help` from another directory. + +### Option C: WSL + +The repository `install.sh` path is for Linux, macOS, and Windows via WSL. Run it from inside your WSL distribution, not from native PowerShell: + +```powershell +wsl --install +wsl +``` + +Then inside WSL: + +```bash +git clone https://github.com/ultraworkers/claw-code +cd claw-code +./install.sh +``` + +## First-run health checks + +Run these before using live prompts: + +```powershell +Set-Location .\claw-code\rust +.\target\debug\claw.exe --help +.\target\debug\claw.exe doctor +.\target\debug\claw.exe status --output-format json +.\target\debug\claw.exe config --output-format json +``` + +`doctor`, `status`, `config`, and `version` support `--output-format json`; do not use a separate `--json` suffix. + +## Safe credential setup + +Set keys only in your local environment or a private `.env` file. Do not paste real keys into shell history shared with others, issue trackers, or documentation. + +Current PowerShell session only: + +```powershell +$env:ANTHROPIC_API_KEY = "sk-ant-REPLACE_ME" +``` + +Persist for future PowerShell windows: + +```powershell +setx ANTHROPIC_API_KEY "sk-ant-REPLACE_ME" +``` + +Open a new terminal after `setx`. To remove a session-local key while testing provider switching: + +```powershell +Remove-Item Env:\ANTHROPIC_API_KEY -ErrorAction SilentlyContinue +``` + +## Safe provider switching examples + +Provider routing is model-prefix first. When multiple credentials exist, choose an explicit model prefix so `claw` does not infer the wrong backend. + +### Anthropic direct + +```powershell +$env:ANTHROPIC_API_KEY = "sk-ant-REPLACE_ME" +Remove-Item Env:\OPENAI_BASE_URL -ErrorAction SilentlyContinue +Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue + +.\target\debug\claw.exe --model "sonnet" prompt "reply with ready" +``` + +### OpenAI-compatible gateway or OpenRouter + +```powershell +Remove-Item Env:\ANTHROPIC_API_KEY -ErrorAction SilentlyContinue +$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1" +$env:OPENAI_API_KEY = "sk-or-v1-REPLACE_ME" + +.\target\debug\claw.exe --model "openai/gpt-4.1-mini" prompt "reply with ready" +``` + +For the default OpenAI-compatible API, omit `OPENAI_BASE_URL` or set it to `https://api.openai.com/v1`, and keep the `openai/` or `gpt-` model prefix explicit. + +### Local OpenAI-compatible server + +Use a loopback URL and a placeholder token unless your local server requires a real one: + +```powershell +Remove-Item Env:\ANTHROPIC_API_KEY -ErrorAction SilentlyContinue +$env:OPENAI_BASE_URL = "http://127.0.0.1:11434/v1" +$env:OPENAI_API_KEY = "local-dev-token" + +.\target\debug\claw.exe --model "llama3.2" prompt "reply with ready" +``` + +If the local server is authless, remove `OPENAI_API_KEY` instead of putting a real cloud key into local testing: + +```powershell +Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue +``` + +### DashScope / Qwen + +```powershell +Remove-Item Env:\ANTHROPIC_API_KEY -ErrorAction SilentlyContinue +$env:DASHSCOPE_API_KEY = "sk-REPLACE_ME" + +.\target\debug\claw.exe --model "qwen-plus" prompt "reply with ready" +``` + +## Windows and WSL notifications + +Notification support is exposed through the `notifications` slash command in the interactive REPL. Use JSON/status commands first to confirm the CLI runs, then configure notifications from the REPL if your workflow needs them. + +Native PowerShell smoke path: + +```powershell +Set-Location .\claw-code\rust +.\target\debug\claw.exe +# inside the REPL: +/notifications +``` + +WSL smoke path: + +```bash +cd claw-code/rust +./target/debug/claw +# inside the REPL: +/notifications +``` + +When moving between PowerShell and WSL, keep provider keys in the environment where `claw` is actually running; Windows user env vars set with `setx` are not automatically the same as WSL shell exports. + +## Troubleshooting checklist + +- `claw` not found: use `claw.exe` on Windows or run the binary by full path (`.\target\debug\claw.exe`). +- `cargo` not found: reopen PowerShell after installing Rust from . +- `401 Invalid bearer token`: put `sk-ant-*` values in `ANTHROPIC_API_KEY`, not `ANTHROPIC_AUTH_TOKEN`. +- Wrong provider selected: add an explicit model prefix such as `openai/gpt-4.1-mini`, `qwen-plus`, or `grok`. +- Release ZIP extracted but command still fails: open a new terminal after updating the user `Path`, or call `& "$env:LOCALAPPDATA\Programs\claw\claw.exe"` directly.