stef-openclaw-skills/docs/installation.md

Installation

This page covers installing the ai-cli-dispatch tool, its prerequisites, and post-install verification.

Prerequisites

• Node.js ≥ 20 (required for tsx, import attributes, and modern node:child_process APIs)
• npm (bundled with Node.js)
• Homebrew (macOS/Linux) — recommended for installing the underlying AI CLI clients (codex, claude, opencode)
• One or more supported AI CLI clients:
  • Codex CLI
  • Claude Code
  • OpenCode

Install the tool

1. Clone the repository

git clone <repository-url> ~/.openclaw/workspace/skills/ai-cli-dispatch
cd ~/.openclaw/workspace/skills/ai-cli-dispatch

If you already have the full stef-openclaw-skills repo checked out, use the path inside it instead:

cd ~/.openclaw/workspace/skills/stef-openclaw-skills/tools/ai-cli-dispatch

2. Install Node dependencies

npm install

This installs:

• tsx — TypeScript execution runtime
• minimist — argument parsing
• typescript — type checking

PATH configuration

The helper script lives at scripts/ai-cli-dispatch. Add it to your shell PATH so OpenClaw (or your terminal) can invoke it without a full path:

# ~/.zshrc or ~/.bashrc
export PATH="$HOME/.openclaw/workspace/skills/ai-cli-dispatch/scripts:$PATH"

Reload your shell:

source ~/.zshrc   # or ~/.bashrc

Verify the script is reachable:

which ai-cli-dispatch
ai-cli-dispatch --help

Optional configuration file

Create ~/.openclaw/ai-cli-dispatch.json to customize client paths and set a default client:

mkdir -p ~/.openclaw
$EDITOR ~/.openclaw/ai-cli-dispatch.json

Example configuration:

{
  "paths": {
    "codex": "/opt/homebrew/bin/codex",
    "claude": "/opt/homebrew/bin/claude",
    "opencode": "/opt/homebrew/bin/opencode"
  },
  "defaultClient": "claude"
}

Configuration precedence

When resolving a client binary, the tool checks sources in this order (first match wins):

1. CLI flag: --codex-path, --claude-path, --opencode-path
2. Environment variable: AI_CLI_CODEX_PATH, AI_CLI_CLAUDE_PATH, AI_CLI_OPENCODE_PATH
3. File config: paths.<client> in ~/.openclaw/ai-cli-dispatch.json
4. System PATH lookup via which / where

The defaultClient follows the same precedence:

1. CLI flag: --default-client
2. Environment variable: AI_CLI_DEFAULT_CLIENT
3. File config: defaultClient in ~/.openclaw/ai-cli-dispatch.json

Install AI CLI clients

Codex

npm install -g @openai/codex

Claude Code

npm install -g @anthropic-ai/claude-code

OpenCode

npm install -g @opencode-ai/opencode

Or via Homebrew where formulas are available:

brew install codex        # if available in your tap
brew install claude-code  # if available in your tap

Verification

1. Check local tool health

ai-cli-dispatch --help

Expected output:

AI CLI Dispatch

Usage:
  ai-cli-dispatch list [--json|--text]
  ai-cli-dispatch run --client <client> --prompt <prompt> [--json|--text]
  ai-cli-dispatch dispatch <prompt> [--client <client>] [--json|--text]
  ai-cli-dispatch --help

Clients: codex, claude, opencode

2. List discovered clients

ai-cli-dispatch list --json

Example output when two clients are installed:

[
  {
    "name": "codex",
    "path": "/opt/homebrew/bin/codex",
    "version": "1.2.3",
    "found": true
  },
  {
    "name": "claude",
    "path": "/opt/homebrew/bin/claude",
    "version": "0.7.8",
    "found": true
  },
  {
    "name": "opencode",
    "found": false
  }
]

3. Run a quick dispatch

ai-cli-dispatch run --client codex --prompt "hello" --json

This should return a JSON result with stdout, stderr, and exitCode.

4. Test keyword dispatch

ai-cli-dispatch dispatch "refactor this using claude"

The tool inspects the prompt for client keywords (claude, codex, opencode, open code) and routes to the matching client.

Troubleshooting

Missing local Node dependencies for ai-cli-dispatch

Run npm install from the skill directory:

cd ~/.openclaw/workspace/skills/ai-cli-dispatch
npm install

Client "codex" not found or not installed

• Ensure the client is installed globally or via Homebrew
• Verify it is on your PATH: which codex
• Or override the path in ~/.openclaw/ai-cli-dispatch.json or with an environment variable

Prompt cannot be empty

The run and dispatch commands require a non-empty --prompt or trailing prompt text.

Config file is not being read

• Verify the file is at exactly ~/.openclaw/ai-cli-dispatch.json
• Check for JSON syntax errors (trailing commas are not allowed)
• Use --debug for deeper troubleshooting if supported by the calling context