# Nodeclaw-Helper

Public helper distribution for NodeClaw integrations.

This release surface exists so users can access the checked helper scripts more directly, while the broader product/docs surface remains on:
- `https://nodenetwork.ovh`
- `https://nodenetwork.ovh/docs`
- `https://nodenetwork.ovh/docs/tools`

## What this release is for

Use this release when you want:
- the launcher-first helper entrypoints
- one remote launcher entrypoint that can fetch the helper payload automatically
- direct per-tool helper scripts when you need an explicit tool-specific path
- a lightweight public distribution surface separate from the larger app repo experience

## Supported tools

Helper-guided targets:
- `claude-code`
- `gemini-cli`
- `codex`
- `hermes`
- `openclaw`
- `opencode`
- `zed`

## Primary path

Use the launcher wizard first, but keep the shell/session boundary honest.

For Claude Code on Linux / macOS shell, the real current-shell env-first path is the sourced launcher command:

```bash
source <(curl -fsSL https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.sh) wizard --tool claude-code
```

If you want a one-shot bootstrap/preview path instead of current-shell apply, you can still run:

```bash
curl -fsSL https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.sh | bash -s -- wizard
```

That child-shell path does not mutate the caller shell for env-first tools.
If you already know the tool, you can preselect it from the sourced launcher wizard or another explicit helper path.

Default behavior for env-capable tools such as `claude-code` is env-first where the current path can really mutate the active shell/session.
Persistent config/file writes are available only when you explicitly choose them in the wizard or another advanced path.

## Advanced / automation

Shell launcher:

```bash
bash ./script/launcher.sh help
bash ./script/launcher.sh list
bash ./script/launcher.sh wizard [--tool <claude-code|gemini-cli|codex|hermes|openclaw|opencode|zed>] [--route-mode <direct|cloudflare>] [--install-mode <auto|env|persistent>]
bash ./script/launcher.sh dry-run --tool <claude-code|gemini-cli|codex|hermes|openclaw|opencode|zed> --route-mode <direct|cloudflare> --install-mode <auto|env|persistent>
bash ./script/launcher.sh apply --tool <claude-code|gemini-cli|codex|hermes|openclaw|opencode|zed> --route-mode <direct|cloudflare> --install-mode <auto|env|persistent>
```

Use these advanced flags when you are automating setup, previewing a non-interactive path, or deliberately choosing a persistent install contract.
For env-first tools such as Claude Code, `bash ./script/launcher.sh apply ... --install-mode env` is still a child-shell path and must refuse honestly instead of claiming current-shell apply. Use the sourced launcher/helper path when you need real same-shell env apply.
Cloudflare remains explicit opt-in; `direct` stays the default launcher route.

PowerShell launcher:

```powershell
.\script\launcher.ps1 -Command help
.\script\launcher.ps1 -Command list
.\script\launcher.ps1 -Command dry-run -Tool <claude-code|gemini-cli|codex|hermes|openclaw|opencode|zed> -RouteMode <direct|cloudflare> -InstallMode <auto|env|persistent>
.\script\launcher.ps1 -Command wizard -Tool <claude-code|gemini-cli|codex|hermes|openclaw|opencode|zed> -RouteMode <direct|cloudflare> -InstallMode <auto|env|persistent>
```

Remote PowerShell launcher:

Two explicit PowerShell entry patterns are supported:

### 1) Run from an existing PowerShell session

Use this as the primary Windows quick-start path.
When PowerShell is already open, set launcher options step by step before running it inside the same session that will later launch the tool.
This is the supported Windows current-session apply standard.

```powershell
$env:NODECLAW_LAUNCHER_COMMAND='wizard'
$env:NODECLAW_LAUNCHER_TOOL='claude-code'      # optional
$env:NODECLAW_LAUNCHER_ROUTE_MODE='cloudflare' # optional
$launcherText = irm https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.ps1
& ([scriptblock]::Create($launcherText))
```

### 2) One-shot launcher invocation from `cmd.exe` or a terminal

Use this only when you want a bootstrap/preview fallback path.
It starts PowerShell, downloads the launcher, and runs it immediately, but it does not make the original parent shell ready for current-session env apply.

```powershell
powershell -ExecutionPolicy Bypass -c "$env:NODECLAW_LAUNCHER_COMMAND='wizard'; $launcherText = irm https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.ps1; & ([scriptblock]::Create($launcherText))"
powershell -ExecutionPolicy Bypass -c "$env:NODECLAW_LAUNCHER_COMMAND='wizard'; $env:NODECLAW_LAUNCHER_TOOL='claude-code'; $launcherText = irm https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.ps1; & ([scriptblock]::Create($launcherText))"
powershell -ExecutionPolicy Bypass -c "$env:NODECLAW_LAUNCHER_COMMAND='wizard'; $env:NODECLAW_LAUNCHER_TOOL='claude-code'; $env:NODECLAW_LAUNCHER_ROUTE_MODE='cloudflare'; $launcherText = irm https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.ps1; & ([scriptblock]::Create($launcherText))"
```

Swap `NODECLAW_LAUNCHER_TOOL='claude-code'` for `codex`, `zed`, `openclaw`, `gemini-cli`, `opencode`, or `hermes` when you want a specific tool preselected.

`gemini-cli` can now use the Cloudflare-protected launcher path through the protected Google / Gemini `v1beta` family when you explicitly opt into Cloudflare mode.

## Claude Code CLI setup posture

`claude-code` uses an env-first helper path through the checked `ANTHROPIC_*` environment contract.

Hosted first-use path (Linux / macOS shell):

```bash
source <(curl -fsSL https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.sh) wizard --tool claude-code
```

Hosted first-use path (Windows PowerShell session):

```powershell
$env:NODECLAW_LAUNCHER_COMMAND='wizard'
$env:NODECLAW_LAUNCHER_TOOL='claude-code'
$launcherText = irm https://darkwingtm.github.io/Nodeclaw-Helper/script/launcher.ps1
& ([scriptblock]::Create($launcherText))
```

If you instead launch PowerShell as a one-shot child process from `cmd.exe` or another terminal, treat that as bootstrap/preview-only rather than current-session apply.

Manual env contract:

```bash
export ANTHROPIC_BASE_URL="https://payg.nodenetwork.ovh"
export ANTHROPIC_AUTH_TOKEN="<nodeclaw_access_key>"
export ANTHROPIC_MODEL="gemini-3.1-flash"
claude --model gemini-3.1-flash
```

Optional compatibility fallbacks when the gateway rejects Anthropic beta headers/features:

```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_INTERLEAVED_THINKING=1
```

Optional Cloudflare-protected helper posture for the same Claude contract/

```bash
export ANTHROPIC_BASE_URL="https://gateway.ai.cloudflare.com/v1/06b7333b2c174700306d7f931d809765/nodenetwork-nodeclaw-payg/custom-nodenetwork/"
export ANTHROPIC_AUTH_TOKEN="<nodeclaw_access_key>"
claude
```

If you explicitly choose persistent mode later, Claude Code can mirror the same env values into `~/.claude/settings.json` or `%USERPROFILE%\.claude\settings.json`.
That persistence path is optional; it is not the default first-use contract.

What the helper manages by default:
- sourced hosted shell path can prompt for missing `NODECLAW_API_KEY` and apply `ANTHROPIC_*` in the caller shell
- the same env-first Claude Code contract without forcing a config-file edit first
- optional helper-guided persistent mode only after an explicit choice

Verify / troubleshoot:
- launch `claude` only after both env vars are active in the same shell that starts Claude Code
- if you used the hosted shell wizard, start Claude Code from that same sourced shell after the wizard applies the env contract
- if the first request fails immediately, verify the target still exposes `/v1/messages` and `/v1/messages/count_tokens`
- if `ANTHROPIC_BASE_URL` points to a non-first-party host, Claude Code MCP tool search remains disabled unless that proxy forwards `tool_reference` blocks correctly

Important boundary:
- Claude Code first-use stays env-first by default; `~/.claude/settings.json` is only for explicit persistent mode
- hosted Linux / macOS shell examples for Claude Code must use the sourced launcher command so the wizard can apply env in the caller shell
- direct/native Claude Code must use the service root `https://payg.nodenetwork.ovh` in `ANTHROPIC_BASE_URL` rather than appending `/v1`
- PowerShell launcher is route-mode-aware in the current checked scope; one-shot child PowerShell paths stay bootstrap/preview-only, while an existing PowerShell session is the supported Windows current-session apply path

## Gemini CLI setup posture

`gemini-cli` now uses an env-first custom-endpoint helper path.

Primary setup contract:

```bash
export GOOGLE_GEMINI_BASE_URL="https://payg.nodenetwork.ovh"
export GEMINI_API_KEY="<nodeclaw_access_key>"
gemini
```

Optional Cloudflare-protected helper posture for the same Gemini contract:

```bash
export GOOGLE_GEMINI_BASE_URL="https://gateway.ai.cloudflare.com/v1/06b7333b2c174700306d7f931d809765/nodenetwork-nodeclaw-payg/custom-nodenetwork/v1beta"
export GEMINI_API_KEY="<nodeclaw_access_key>"
gemini
```

What the helper manages:
- shell/PowerShell env snippet generation
- profile source block generation
- helper-guided preview/apply flow for that same env-based setup

Important boundary:
- effective Google / Gemini-shaped route family still resolves under `v1beta`
- the helper does **not** use ACP as the setup story anymore
- shell helper can apply the managed env/profile path
- PowerShell one-shot/bootstrap launcher paths stay preview-only, while the direct Gemini PowerShell helper can still write the managed env/profile files and an existing PowerShell session remains the Windows apply standard where session env apply matters

## Hermes helper path

`hermes` now has a dedicated helper-guided profile path for the NodeClaw custom endpoint.

Primary helper contract:

```bash
export HERMES_NODECLAW_API_KEY="<nodeclaw_access_key>"
export HERMES_NODECLAW_BASE_URL="https://payg.nodenetwork.ovh/v1"
bash ./script/setup-hermes-nodeclaw.sh --dry-run
bash ./script/setup-hermes-nodeclaw.sh
```

Optional Cloudflare-protected helper posture for the same Hermes profile-local contract/

```bash
export HERMES_NODECLAW_API_KEY="<nodeclaw_access_key>"
export HERMES_NODECLAW_BASE_URL="https://gateway.ai.cloudflare.com/v1/06b7333b2c174700306d7f931d809765/nodenetwork-nodeclaw-payg/custom-nodenetwork/"
bash ./script/setup-hermes-nodeclaw.sh --dry-run
bash ./script/setup-hermes-nodeclaw.sh
```

What the helper manages:
- one dedicated Hermes profile such as `~/.hermes/profiles/nodeclaw-hermes`
- profile-local `.env`
- profile-local `config.yaml`
- profile-local `SOUL.md`
- optional clone-based bootstrap from another Hermes profile before the NodeClaw-specific files are rewritten

Important boundary:
- the helper assumes Hermes profiles are separate Hermes home directories
- the first-wave helper target is still inventory-first and does not by itself promote Hermes into Home or the main `/docs` onboarding flow
- PowerShell one-shot/bootstrap launcher paths stay preview-only, but the direct Hermes PowerShell helper can write the profile-local files now and an existing PowerShell session remains the Windows apply standard where session env apply matters
- this release wave does not claim that Hermes has been installed or live-tested against a real target service yet; the current proof boundary is docs-first + helper-payload accuracy

## Direct per-tool helpers

Linux / macOS shell helpers:
- `script/setup-claude-code-nodeclaw.sh`
- `script/setup-gemini-cli-nodeclaw.sh`
- `script/setup-codex-nodeclaw.sh`
- `script/setup-hermes-nodeclaw.sh`
- `script/setup-openclaw-nodeclaw.sh`
- `script/setup-opencode-nodeclaw.sh`
- `script/setup-zed-nodeclaw.sh`

Windows PowerShell helpers:
- `script/setup-claude-code-nodeclaw.ps1`
- `script/setup-gemini-cli-nodeclaw.ps1`
- `script/setup-codex-nodeclaw.ps1`
- `script/setup-hermes-nodeclaw.ps1`
- `script/setup-openclaw-nodeclaw.ps1`
- `script/setup-opencode-nodeclaw.ps1`
- `script/setup-zed-nodeclaw.ps1`

## Current support boundary

- Launcher remains the generic entrypoint.
- Route mode defaults to `direct`, while `cloudflare` is explicit opt-in at the launcher surface.
- Checked Cloudflare-capable targets are `claude-code`, `codex`, `zed`, `opencode`, `hermes`, and `gemini-cli`; `openclaw` can use Cloudflare only when `NODECLAW_COMPATIBILITY` is `openai` or `anthropic`.
- `gemini-cli` now uses the protected Google / Gemini `v1beta` family when `--route-mode cloudflare` is requested, while direct mode keeps the native Gemini root.
- `opencode` and `hermes` keep the same custom-provider-root contract in both modes; launcher only swaps which root/base gets injected.
- Shell helper paths can apply changes where the checked script supports it.
- PowerShell launcher paths are route-mode-aware; one-shot/bootstrap launcher paths stay preview-only, while existing-session PowerShell apply works only inside the PowerShell session that will later launch the tool.
- Gemini helper support is env/snippet/profile oriented, not file-mutation-first like some other tools.
- Hermes helper support is profile-local and writes `.env` / `config.yaml` / `SOUL.md` for one dedicated Hermes home/profile path.
- `openclaw` still requires the local `openclaw` command to already exist in `PATH`.
- `hermes` helper needs the local `hermes` command when apply mode is used for real profile creation outside a custom-home-only write path.
- Default checked OpenAI-compatible helper base in several tools is `https://payg.nodenetwork.ovh/v1`.
- Gemini helper examples use the service root `https://payg.nodenetwork.ovh`, while the effective Google / Gemini-shaped route family still resolves under `v1beta`.
- Default checked model used in several helpers remains `gpt-5.4` unless the target tool expects another provider-native model id.
- Checked local smoke coverage now verifies launcher route-mode behavior plus setup-script dry-run contracts in scope; this is not live provider, deploy, or hosted Pages proof.

## Recommended usage order

1. Start from the main NodeClaw docs/product surface when you want the full context.
2. Use `launcher.sh` or `launcher.ps1` with `wizard` as the default first-use path.
3. Let the wizard choose the right setup flow and keep env-first where the tool supports it.
4. Use advanced `dry-run`, `apply`, or direct per-tool scripts only when you intentionally need a non-interactive/operator path.
5. Choose persistent mode only when you deliberately want config/file state beyond the current shell or session.

## Related release files

- `index.html`
- `manifest.json`
- `PUBLISHING.md`