Elgato_dark/openclaw-nerve
1
0
Fork 0
mirror of https://github.com/daggerhashimoto/openclaw-nerve synced 2026-04-21 10:37:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: add AI agent setup guides (#182)

Browse source 
* docs: add AI agent setup guides
* docs: keep AI setup guides out of root README
* docs: add service-manager runtime guidance
* fix(installer): use prod command in manual start hints
* fix(installer): include install dir in manual start hints
This commit is contained in:
Çağın Dönmez 2026-03-28 19:33:03 +03:00 committed by GitHub
parent c89155f9aa
commit 5393ad48c8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 439 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
docs/AI_SETUP.md Normal file
View file

@ -0,0 +1,198 @@
# AI Agent Setup
Nerve supports agent-driven installation.
If you want an AI agent to install, configure, and validate Nerve, the canonical raw instruction file is:
- [`INSTALL.md`](./INSTALL.md)
- raw URL: `https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md`
Use that file as the operational contract.
Use this page for the human-readable explanation, boundaries, and topology map.
## Copy-paste prompt
```text
Install, configure, and validate Nerve on this machine.
Fetch and follow instructions from:
https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md
```
## Default agent behavior
Unless you say otherwise, agents should use these defaults:
- local-first
- localhost-only by default
- `~/nerve` as the install path
- installer-first (`install.sh`)
- setup wizard first
- validate before reporting completion
That means the common happy path is:
1. detect an existing OpenClaw gateway
2. install Nerve
3. run setup
4. start or restart Nerve
5. validate the UI and gateway connection
## What agents may do automatically
For the default local path, agents may automatically:
- inspect the current machine and existing install state
- detect whether `~/nerve` already exists
- detect whether OpenClaw is installed and reachable
- detect the gateway token and gateway URL
- install missing core prerequisites for the local path
- run the Nerve installer
- run the setup wizard
- use defaults mode for local-only setup when no TTY is available
- write a minimal local `.env` if the wizard cannot be used
- restart local services or processes
- run validation and smoke checks
Agents may also apply minimal localhost-safe OpenClaw changes needed for the default path, such as local origin allowlisting, local pairing fixes, or required local tool allow entries.
## What requires confirmation
Agents should ask before they do anything that changes exposure, trust, or install ownership.
That includes:
- installing OpenClaw
- exposing Nerve beyond localhost
- LAN access
- public internet exposure
- reverse proxy setup
- Tailscale setup or topology changes
- destructive reinstall, replacement, or deletion
- remote gateway auth or allowlist changes
- cloud-hosted assumptions that materially change the security posture
Short version: local repair and local setup can be automated. Public or destructive changes need consent.
## Dependency behavior
Nerve is not a standalone app. It depends on an OpenClaw gateway.
Expected agent behavior:
1. look for an existing reachable gateway first
2. prefer using that gateway
3. if none is found, explain the dependency clearly
4. ask before installing OpenClaw
For the default same-machine flow, agents may make the smallest safe local OpenClaw fixes required for Nerve to connect. For remote or public gateway changes, they should stop and ask.
## Topology map
Choose the guide that matches the intended setup:
- **Local / same machine:** [DEPLOYMENT-A.md](./DEPLOYMENT-A.md)
- **Hybrid / local Nerve + remote gateway:** [DEPLOYMENT-B.md](./DEPLOYMENT-B.md)
- **Cloud / remote Nerve:** [DEPLOYMENT-C.md](./DEPLOYMENT-C.md)
- **Add Tailscale to an existing install:** [TAILSCALE.md](./TAILSCALE.md)
Recommended default: start with the local setup unless you already know you need something else.
## Done criteria
An agent should only report success when all of these are true:
- Nerve is installed at the intended path
- Nerve starts successfully
- it points at the intended OpenClaw gateway
- access and auth match the requested mode
- the smoke test passes
A script finishing is not enough. A valid install must actually respond and connect.
## Smoke test expectations
Keep validation minimal and real:
1. confirm the Nerve service or process is running
2. confirm the expected URL responds
3. confirm the intended gateway responds
4. confirm `.env` matches the intended gateway
5. if auth is enabled, confirm the login surface or protected access path is present
Typical local checks:
```bash
openclaw gateway status
curl -fsS http://127.0.0.1:18789/health
curl -fsS http://127.0.0.1:3080/health
```
For remote or custom setups, agents should adjust the URLs to match the requested topology.
## Failure and recovery behavior
Agents should fail clearly, not vaguely.
### No OpenClaw gateway found
Explain that Nerve depends on OpenClaw and ask before installing it.
### Installer or setup wizard unavailable
Use the smallest correct fallback:
- clone the repo if needed
- `npm install`
- `npm run setup` when available
- if local-only and no TTY is available, `npm run setup -- --defaults`
- if needed, write a minimal `.env`, then build and start manually
### Existing install already present
Inspect it first. Prefer restart, repair, or reconfigure. Ask before replacing or deleting anything.
### Port, auth, or access mismatch
Adjust the config, restart, and revalidate. Do not declare success just because the process exists.
### Remote or public topology requested without details
Ask for the missing details instead of guessing. This especially matters for Tailscale, reverse proxies, public domains, and remote gateway allowlists.
## Example prompts
### Default local install
```text
Install, configure, and validate Nerve on this machine.
Use the safest local-first path and keep it localhost-only unless you need my approval.
Fetch and follow instructions from:
https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md
```
### Local Nerve + existing remote gateway
```text
Install Nerve on this machine and connect it to my existing remote OpenClaw gateway.
Do not expose Nerve beyond localhost unless I approve it.
If remote gateway config needs changing, tell me before you do it.
Fetch and follow instructions from:
https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md
```
### Tailscale setup
```text
Install Nerve and make it reachable over Tailscale.
Ask before making any exposure or gateway allowlist changes.
Use the repo's Tailscale guidance instead of inventing a new flow.
Fetch and follow instructions from:
https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md
```
### Existing install repair
```text
Inspect my existing Nerve install, repair it if needed, and validate it.
Do not reinstall or delete anything unless you ask first.
Fetch and follow instructions from:
https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/docs/INSTALL.md
```

233
docs/INSTALL.md Normal file
View file

@ -0,0 +1,233 @@
# Nerve Agent Install Contract
Use this file as the operational contract when you are installing, configuring, or validating Nerve on a machine.
## Hard gate
You must be able to:
- read files
- run shell commands
Supported operating systems:
- macOS
- Linux
Stop and say so if any of the following are true:
- you cannot read files
- you cannot run shell commands
- the machine is not macOS or Linux
- the request would require you to invent a Windows flow
Do not claim success without validation.
## Default behavior
Unless the user clearly asks for something else, use these defaults:
- install path: `~/nerve`
- preferred install method: this repo's `install.sh`
- preferred initial topology: local / same machine
- preferred access mode: localhost-only
- preferred config path: setup wizard first
- if the setup wizard is unavailable, skipped, or fails: fall back to explicit manual config
- install, configure, and validate before reporting completion
## Existing install handling
If `~/nerve` already exists:
1. inspect it first
2. determine whether it is an existing Nerve install
3. prefer safe validation, restart, repair, or non-destructive reconfigure work
4. ask before reinstalling, replacing, deleting, or hard-resetting anything
## OpenClaw dependency handling
Nerve depends on an OpenClaw gateway.
You must:
1. detect whether a usable gateway already exists
2. prefer using an existing reachable gateway
3. explain the dependency if no usable gateway is found
4. ask before installing OpenClaw if it is missing
You may apply minimal localhost-safe OpenClaw changes automatically when needed for the default local path. Examples:
- adding missing local control UI origins
- adding required gateway tool allow entries such as `cron` and `gateway`
- fixing local device pairing or scopes needed for Nerve to connect
Ask first before any OpenClaw change that is remote, public, security-sensitive, destructive, or changes network exposure.
## Prerequisite handling
For supported local installs, you may automatically install missing core prerequisites required by the installer or build flow, including package-manager-installed dependencies such as:
- Node.js 22+
- npm
- git
- build tools required for native modules
Ask before optional or network-affecting extras such as:
- Tailscale setup
- reverse proxy setup
- public DNS, TLS, or internet exposure changes
If prerequisite installation is impossible, fail clearly and say what is missing.
## Consent boundaries
Ask for confirmation before any of the following:
- installing OpenClaw
- exposing Nerve beyond localhost
- LAN exposure
- public internet exposure
- reverse proxy setup
- Tailscale changes
- cloud-hosted assumptions that change exposure or security posture
- destructive reinstall, replacement, deletion, or reset actions
- remote gateway allowlist or auth changes
## Auto-allowed actions
For the common local path, you may automatically:
- inspect current install state
- inspect local gateway state
- detect the gateway token and gateway URL
- run the installer
- run the setup wizard
- use defaults mode for local-only setup when no TTY is available
- write minimal manual config if the wizard cannot be used
- restart local services or processes
- run validation and smoke checks
## Common-path install flow
Follow this order unless the user explicitly asks for a different topology.
### 1. Inspect before changing
Check:
- whether `~/nerve` already exists
- whether `openclaw` is installed
- whether the OpenClaw gateway is reachable
- whether a gateway token can be detected
### 2. Prefer the installer
If you are inside a local checkout of this repo, prefer:
```bash
./install.sh
```
If you are operating from GitHub or a raw-doc context without a local checkout, prefer:
```bash
curl -fsSL https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/install.sh | bash
```
### 3. Prefer the setup wizard
If the installer finishes and the setup wizard is available, use it.
If no TTY is available and the target remains the safe local path, you may use:
```bash
cd ~/nerve
npm run setup -- --defaults
```
If the requested topology is LAN, Tailscale, remote gateway, cloud, or any other non-localhost path, do not guess. Ask first unless the user already specified that topology clearly.
### 4. Manual fallback when needed
If the installer or wizard cannot be used, do the smallest correct manual fallback.
If the repo is not present locally:
```bash
git clone https://github.com/daggerhashimoto/openclaw-nerve.git ~/nerve
cd ~/nerve
npm install
```
If you need explicit minimal local config, write `.env` with at least:
```bash
PORT=3080
HOST=127.0.0.1
GATEWAY_URL=http://127.0.0.1:18789
GATEWAY_TOKEN=<detected-token>
```
Then handle runtime like this:
1. if the installer already configured a service manager, use that instead of starting a duplicate foreground process
2. on Linux, check for `systemd` service management via `nerve.service`
3. on macOS, check for `launchd` management via `~/Library/LaunchAgents/com.nerve.server.plist`
4. if no service manager is configured, run Nerve directly with the production entrypoint
Typical commands:
```bash
# build artifacts
npm run build
# Linux, service managed
sudo systemctl restart nerve.service
# macOS, service managed
launchctl stop com.nerve.server || true
launchctl start com.nerve.server
# no service manager present
npm run prod
```
## Topology branching
Stay self-contained for the common path, then branch by user intent:
- Local / same machine: [DEPLOYMENT-A.md](./DEPLOYMENT-A.md)
- Hybrid / remote gateway + local Nerve: [DEPLOYMENT-B.md](./DEPLOYMENT-B.md)
- Cloud / remote Nerve: [DEPLOYMENT-C.md](./DEPLOYMENT-C.md)
- Tailscale retrofit: [TAILSCALE.md](./TAILSCALE.md)
Choose the branch based on the user's intended topology, not on low-level subsystem details.
## Done criteria
Only report success when all of the following are true:
- Nerve is installed at the intended path
- Nerve starts successfully
- it is configured against the intended OpenClaw gateway
- access and auth behavior match the chosen mode
- a minimal smoke test passes
## Smoke test
Keep the smoke test small and explicit.
1. Confirm the Nerve process or service is running.
2. Confirm the expected Nerve URL responds.
- local default: `http://127.0.0.1:3080/health`
3. Confirm the intended OpenClaw gateway is reachable.
4. Confirm `.env` points to that gateway.
5. If auth is enabled or network access was requested, confirm the login surface or expected protected access behavior is present.
Useful checks:
```bash
openclaw gateway status
curl -fsS http://127.0.0.1:18789/health
curl -fsS http://127.0.0.1:3080/health
```
Adjust host, port, and URL to match the chosen topology.
## Failure handling
If any step fails, report:
- the exact failed step
- what you checked
- what you changed
- what worked
- what still needs user input or approval
Do not use vague completion text. Do not loop blindly.

5
docs/README.md
View file

@ -14,6 +14,11 @@ Use this folder as the docs hub for Nerve.
- [Agent Markers](./AGENT-MARKERS.md)
- [Code Review](./CODE_REVIEW.md)
## Agent-Driven Setup
- [AI Agent Setup](./AI_SETUP.md)
- [Nerve Agent Install Contract](./INSTALL.md)
## Deployment Guides
- [Run everything on one machine](./DEPLOYMENT-A.md)

6
install.sh
View file

@ -1191,7 +1191,7 @@ if [[ "$(uname -s)" == "Darwin" ]]; then
if [[ "$(echo "$answer" | tr "[:upper:]" "[:lower:]")" != "n" ]]; then
setup_launchd
else
ok "Skipped — start manually with: npm start"
ok "Skipped — start manually with: cd ${INSTALL_DIR} && npm run prod"
fi
else
info "Cannot read input — installing launchd service by default"
@ -1229,7 +1229,7 @@ elif command -v systemctl &>/dev/null; then
if [[ "$(echo "$answer" | tr "[:upper:]" "[:lower:]")" != "n" ]]; then
setup_systemd
else
ok "Skipped — start manually with: npm start"
ok "Skipped — start manually with: cd ${INSTALL_DIR} && npm run prod"
fi
else
info "Cannot read input — installing systemd service by default"
@ -1301,7 +1301,7 @@ else
echo -e " ${DIM}Restart: sudo systemctl restart nerve.service${NC}"
echo -e " ${DIM}Logs: sudo journalctl -u nerve.service -f${NC}"
else
echo -e " ${DIM}Start: cd ${INSTALL_DIR} && npm start${NC}"
echo -e " ${DIM}Start: cd ${INSTALL_DIR} && npm run prod${NC}"
fi
fi
echo ""