merge S-602 into M6
This commit is contained in:
@@ -0,0 +1,219 @@
|
||||
# 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](https://github.com/openai/codex)
|
||||
- [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)
|
||||
- [OpenCode](https://github.com/opencode-ai/opencode)
|
||||
|
||||
## Install the tool
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/skills/stef-openclaw-skills/tools/ai-cli-dispatch
|
||||
```
|
||||
|
||||
### 2. Install Node dependencies
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# ~/.zshrc or ~/.bashrc
|
||||
export PATH="$HOME/.openclaw/workspace/skills/ai-cli-dispatch/scripts:$PATH"
|
||||
```
|
||||
|
||||
Reload your shell:
|
||||
|
||||
```bash
|
||||
source ~/.zshrc # or ~/.bashrc
|
||||
```
|
||||
|
||||
Verify the script is reachable:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw
|
||||
$EDITOR ~/.openclaw/ai-cli-dispatch.json
|
||||
```
|
||||
|
||||
Example configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
npm install -g @opencode-ai/opencode
|
||||
```
|
||||
|
||||
Or via Homebrew where formulas are available:
|
||||
|
||||
```bash
|
||||
brew install codex # if available in your tap
|
||||
brew install claude-code # if available in your tap
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### 1. Check local tool health
|
||||
|
||||
```bash
|
||||
ai-cli-dispatch --help
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```bash
|
||||
ai-cli-dispatch list --json
|
||||
```
|
||||
|
||||
Example output when two clients are installed:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
ai-cli-dispatch run --client codex --prompt "hello" --json
|
||||
```
|
||||
|
||||
This should return a JSON result with `stdout`, `stderr`, and `exitCode`.
|
||||
|
||||
### 4. Test keyword dispatch
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user