From 60de59627c44fb3339116eeb2c17d86fdcbae0e1 Mon Sep 17 00:00:00 2001 From: Eyejoker Date: Fri, 13 Mar 2026 20:04:46 +0900 Subject: [PATCH] docs: complete setup guide with step-by-step instructions Add clone, install, CLI auth, env files, systemd templates, channel registration with sqlite examples. Move secrets to EnvironmentFile instead of inline systemd Environment. --- README.md | 155 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 124 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 9dbcc67..032cec5 100644 --- a/README.md +++ b/README.md @@ -127,31 +127,135 @@ Skills are managed from a single source of truth (`~/.claude/skills/` on the ser - Linux (Ubuntu 22.04+) or macOS - Node.js 20+ -- [Claude Code CLI](https://claude.ai/download) +- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) - [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`) +- Two Discord bot tokens (one per agent) — create at [Discord Developer Portal](https://discord.com/developers/applications) -### Environment Variables +### 1. Clone and Install ```bash -# .env -DISCORD_BOT_TOKEN= # Claude Code bot token -DISCORD_CODEX_BOT_TOKEN= # Codex bot token (optional, for dual-bot) -ANTHROPIC_API_KEY= # Or use OAuth (CLAUDE_CODE_OAUTH_TOKEN) -OPENAI_API_KEY= # For Codex -CODEX_MODEL= # Default codex model -CODEX_EFFORT= # Default reasoning effort (low/medium/high) +git clone https://github.com/phj1081/nanoclaw.git +cd nanoclaw +npm install +npm run build:runners # installs + builds both agent-runner and codex-runner +npm run build # builds main project ``` -### Service Management (Linux) +### 2. Authenticate CLIs ```bash -systemctl --user start nanoclaw # Claude Code service -systemctl --user start nanoclaw-codex # Codex service -systemctl --user restart nanoclaw nanoclaw-codex # Restart both -journalctl --user -u nanoclaw -f # Follow logs +# Claude Code — opens browser for OAuth login +claude login + +# Codex — set API key +export OPENAI_API_KEY=sk-... ``` -### Service Management (macOS) +### 3. Environment Variables + +Create `.env` in the project root: + +```bash +# .env — shared config (read by both services) +DISCORD_BOT_TOKEN= # Claude Code Discord bot token +ASSISTANT_NAME=claude # Bot trigger name (@claude) +ANTHROPIC_API_KEY= # Or use OAuth (claude login) +OPENAI_API_KEY= # For Codex +``` + +For dual-service setup, create `.env.codex` for Codex-specific overrides: + +```bash +# .env.codex — Codex service secrets (loaded via systemd EnvironmentFile) +DISCORD_BOT_TOKEN= # Codex Discord bot token (different from above) +``` + +> **Security**: Never put tokens in systemd service files or commit them to git. Use `.env` files with restricted permissions (`chmod 600`). + +### 4. Systemd Services (Linux) + +Create `~/.config/systemd/user/nanoclaw.service`: + +```ini +[Unit] +Description=NanoClaw Claude Code +After=network.target + +[Service] +Type=simple +ExecStart=/path/to/node /path/to/nanoclaw/dist/index.js +WorkingDirectory=/path/to/nanoclaw +Restart=always +RestartSec=5 +Environment=HOME=/home/youruser +Environment=PATH=/path/to/node/bin:/usr/local/bin:/usr/bin:/bin + +[Install] +WantedBy=default.target +``` + +Create `~/.config/systemd/user/nanoclaw-codex.service`: + +```ini +[Unit] +Description=NanoClaw Codex +After=network.target + +[Service] +EnvironmentFile=/path/to/nanoclaw/.env.codex +Type=simple +ExecStart=/path/to/node /path/to/nanoclaw/dist/index.js +WorkingDirectory=/path/to/nanoclaw +Restart=always +RestartSec=5 +Environment=HOME=/home/youruser +Environment=PATH=/path/to/node/bin:/usr/local/bin:/usr/bin:/bin +Environment=ASSISTANT_NAME=codex +Environment=NANOCLAW_STORE_DIR=/path/to/nanoclaw/store-codex +Environment=NANOCLAW_DATA_DIR=/path/to/nanoclaw/data-codex +Environment=NANOCLAW_GROUPS_DIR=/path/to/nanoclaw/groups-codex + +[Install] +WantedBy=default.target +``` + +Then enable and start: + +```bash +systemctl --user daemon-reload +systemctl --user enable nanoclaw nanoclaw-codex +systemctl --user start nanoclaw nanoclaw-codex + +# Logs +journalctl --user -u nanoclaw -f +journalctl --user -u nanoclaw-codex -f +``` + +### 5. Register Discord Channels + +Channels are stored in each service's SQLite database (`registered_groups` table). Use the IPC auth endpoint or insert directly: + +```bash +# Example: register a channel for Claude Code +sqlite3 store/nanoclaw.db "INSERT INTO registered_groups (jid, name, folder, agent_type, trigger_pattern) VALUES ('dc:CHANNEL_ID', 'my-channel', 'my-channel', 'claude-code', '@claude');" + +# Example: register a channel for Codex +sqlite3 store-codex/nanoclaw.db "INSERT INTO registered_groups (jid, name, folder, agent_type, trigger_pattern) VALUES ('dc:CHANNEL_ID', 'my-channel', 'my-channel', 'codex', '@codex');" +``` + +Fields: + +| Field | Description | +|-------|-------------| +| `jid` | `dc:` | +| `name` | Display name | +| `folder` | Group folder name (workspace directory) | +| `agent_type` | `claude-code`, `codex`, or `both` | +| `trigger_pattern` | Regex for activation (e.g., `@claude`) | +| `work_dir` | Optional working directory override | +| `container_config` | Optional JSON (e.g., `{"codexEffort":"high"}`) | + +### macOS (launchd) ```bash launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist @@ -159,25 +263,14 @@ launchctl load ~/Library/LaunchAgents/com.nanoclaw-codex.plist launchctl kickstart -k gui/$(id -u)/com.nanoclaw ``` -## Channel Registration - -Channels are registered in each service's SQLite database (`registered_groups` table). Each entry specifies: - -- **jid**: Discord channel ID (`dc:`) -- **folder**: Group folder name (matches Discord channel name) -- **trigger_pattern**: Regex for bot activation (`@claude` or `@codex`) -- **agent_type**: `claude-code`, `codex`, or `both` (shared channel) -- **work_dir**: Working directory for the agent -- **container_config**: JSON config (e.g., `{"codexEffort":"high"}`) - ## Development ```bash -npm run build # Build main project -cd container/agent-runner && npm run build # Build Claude runner -cd container/codex-runner && npm run build # Build Codex runner -npm run dev # Dev mode with hot reload -npm test # Run tests +npm install # Install dependencies +npm run build # Build main project +npm run build:runners # Install + build both runners +npm run dev # Dev mode with hot reload +npm test # Run tests ``` ## License