openbroker 1.9.0 → 1.9.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.9.1] - 2026-06-22
+
+### Changed
+- Added `openbroker install --codex` and `npx openbroker@latest install --codex` for one-command Codex skill installation, persistent CLI installation, and restricted API-wallet onboarding.
+- Made restricted API-wallet onboarding the recommended interactive default.
+- Added `openbroker setup --api-wallet` for deterministic agent setup without the wallet-selection prompt.
+- Updated the Codex skill to install the CLI, hand the browser approval URL to the user, wait for authorization, and verify the connected master account without exposing private keys.
+
 ## [1.5.0] - 2026-06-01
 
 ### Added

package/README.md

@@ -8,13 +8,23 @@ Hyperliquid trading CLI. Execute orders, manage positions, and run trading strat
 npm install -g openbroker
 ```
 
+### Codex: one-command install
+
+Install the Codex skill, persistent CLI, and restricted API-wallet onboarding flow:
+
+```bash
+npx openbroker@latest install --codex
+```
+
+When the command prints an approval URL, open it and connect the funded master Hyperliquid account you want OpenBroker to trade on. Restart Codex or start a new thread when setup finishes, then invoke `$openbroker`.
+
 ## Quick Start
 
 ```bash
-# 1. Setup (generates wallet, creates config, approves builder fee)
-openbroker setup
+# 1. Setup a restricted API wallet (recommended for agents)
+openbroker setup --api-wallet
 
-# 2. Fund your wallet with USDC on Arbitrum, then deposit at https://app.hyperliquid.xyz/
+# 2. Open the printed approval link and connect your funded master Hyperliquid wallet
 
 # 3. Start trading
 openbroker account                          # View account info
@@ -27,18 +37,20 @@ openbroker search --query GOLD              # Find markets
 ### Setup
 
 ```bash
-openbroker setup                # One-command setup (wallet + config + builder approval)
+npx openbroker@latest install --codex  # Codex skill + CLI + API-wallet onboarding
+openbroker setup --api-wallet   # Recommended: restricted agent wallet + browser approval
+openbroker setup                # Interactive; API wallet is the default
 ```
 
 The setup command handles everything automatically:
-- Generates a fresh trading wallet (recommended for agents) or accepts your existing private key
+- Generates a restricted API wallet by default, or accepts another wallet mode interactively
 - Saves configuration to `~/.openbroker/.env` (permissions `0600`)
-- Approves the builder fee (required for trading)
+- Prints a browser approval link and waits for master-wallet authorization
 
 Setup offers three modes:
-1. **Generate fresh wallet** (recommended for agents) — cleanest option, no browser steps
+1. **Generate fresh wallet** — separately funded wallet, no browser steps
 2. **Import existing key** — use a key you already have
-3. **Generate API wallet** — restricted wallet requiring browser approval from a master wallet
+3. **Generate API wallet** (default and recommended for agents) — can trade but cannot withdraw; requires browser approval from a master wallet
 
 ---
 
@@ -717,25 +729,24 @@ export HYPERLIQUID_NETWORK=mainnet       # Optional: mainnet (default) or testne
 export HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets
 ```
 
-### Fresh Wallet Setup (Recommended for Agents)
+### API Wallet Setup (Recommended for Agents)
 
-The simplest setup for agents — generates a dedicated wallet, auto-approves the builder fee, and is ready to trade after funding:
+The safest default for agents delegates trading from an API wallet that cannot withdraw. The CLI prints an approval URL, waits for the funded master wallet to authorize it, and then saves the master account mapping automatically:
 
 ```bash
-openbroker setup    # Choose option 1, fund with USDC, start trading
+openbroker setup --api-wallet
 ```
 
-### API Wallet Setup (Alternative)
+Open the printed `https://openbroker.dev/approve?agent=...` link, connect the intended master Hyperliquid wallet, and approve `ApproveAgent` plus the 1 bps `ApproveBuilderFee` transaction. If approval times out, rerun the same command; OpenBroker resumes the incomplete setup without generating a new key.
+
+### Fresh Wallet Setup (Alternative)
 
-For delegated trading without moving funds, use an API wallet:
+Run interactive setup and explicitly choose option 1 to create a separately funded wallet:
 
 ```bash
-export HYPERLIQUID_PRIVATE_KEY="0x..."        # API wallet private key
-export HYPERLIQUID_ACCOUNT_ADDRESS="0x..."    # Main account address
+openbroker setup
 ```
 
-**Note:** API wallets require browser approval from the master wallet. The master wallet signs `ApproveAgent` and `ApproveBuilderFee` transactions via the approval URL provided during setup.
-
 ## Builder Fee
 
 Open Broker charges **1 bps (0.01%)** per trade to fund development. The builder fee is automatically approved during `openbroker setup`.

package/SKILL.md

@@ -1,38 +1,74 @@
 ---
 name: openbroker
-description: Hyperliquid trading CLI skill for agents. Use when an agent needs to inspect markets/accounts, place or manage perp/spot/HIP-4 orders, or write and run Hyperliquid trading automations directly through the `openbroker` CLI without requiring the OpenClaw plugin.
-license: MIT
-compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
-homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.3.2"}
-allowed-tools: Bash(openbroker:*)
+description: Install, onboard, and operate the OpenBroker Hyperliquid CLI for market and account inspection, restricted API-wallet setup, perp/HIP-3/spot/HIP-4 trading, order management, and TypeScript automations. Use when Codex needs to set up OpenBroker, run or explain `openbroker` commands, inspect Hyperliquid state, safely preview or execute trades, or create and debug OpenBroker automations.
 ---
 
 # OpenBroker — Hyperliquid CLI skill
 
-OpenBroker is first a CLI. The OpenClaw plugin is optional: use `ob_*` tools when present for common structured calls, but keep the CLI model in mind because it is the complete surface area and the safest fallback.
+Use the `openbroker` CLI as the canonical interface. Prefer structured JSON output for inspection and dry runs before live writes.
 
 ## Operating rules
 
 - For unfamiliar assets, **search before trading**. Hyperliquid has main perps, HIP-3 perps, spot markets, and HIP-4 outcomes that can share names.
 - Prefer `--json` for machine-readable info commands.
-- Before any write, verify the asset, account, open positions/orders, size, and whether the action should be reduce-only.
-- For new or changed trading logic, start with `--dry`, inspect the plan/audit trail, then go live only when that matches the user’s intent.
+- Before any write, verify the network, trading account, asset, side, size, open positions/orders, and whether the action should be reduce-only.
+- Use `--dry` for proposed trades and new or changed trading logic. Execute live only when the user explicitly requests live execution and the dry-run plan matches that intent.
+- Never infer a live trade size, switch to mainnet, or create/import/export a wallet without explicit user direction.
+- Never print, echo, log, or expose private keys or seed material. Refer only to the configured signing wallet address when diagnosing identity.
 - Treat CLI output as exchange state, not just prose: parse order IDs, balances, fills, and errors instead of assuming success.
 
-## Setup and identity
+## First-run installation and API-wallet onboarding
+
+Use the following flow when the user asks to install, set up, or use OpenBroker. Do not ask the user for a private key.
+
+For a fresh Codex installation, prefer the unified harness installer:
+
+```bash
+npx --yes openbroker@latest install --codex
+```
+
+This installs or updates the Codex skill, installs the persistent `openbroker` CLI, and starts restricted API-wallet onboarding. Keep the command attached while it prints the browser approval link and polls for authorization.
+
+If the unified installer is unavailable or the skill is already installed, first check whether Node.js 22+ and the CLI are installed:
 
 ```bash
-npm install -g openbroker
-openbroker setup
-openbroker account --json
+node --version
+command -v openbroker
+openbroker --version
 ```
 
-`setup` supports:
+Require OpenBroker 1.9.1 or newer. When the user explicitly asks to set up OpenBroker, install or upgrade the CLI as part of that request, using the normal approval flow for global or network writes:
 
-1. **Fresh wallet** — simplest for agents; builder fee approval is handled automatically.
+```bash
+npm install -g openbroker@latest
+```
+
+Public market-data commands such as `search`, `markets`, `funding`, `candles`, and `trades` work without wallet setup. For account-specific reads or trading, prefer a restricted API wallet because it can trade on the user's master Hyperliquid account but cannot withdraw funds.
+
+Run setup in an interactive terminal session and select the API-wallet flow directly:
+
+```bash
+openbroker setup --api-wallet
+```
+
+The command generates and stores the API wallet key locally in `~/.openbroker/.env` with mode `0600`, prints an approval URL, and waits up to ten minutes for browser approval. Handle that handoff as follows:
+
+1. Keep the setup process running. Polling output is expected; do not treat it as a stuck command.
+2. Capture the `https://openbroker.dev/approve?agent=...` URL from terminal output and immediately show it to the user as a clickable link.
+3. Ask the user to open the link, connect the funded master Hyperliquid wallet they want OpenBroker to trade on, review the addresses and network, and sign the requested approvals. On mainnet this authorizes the API agent and the 1 bps builder fee; it does not grant withdrawal access.
+4. Never ask the user to paste a master-wallet or API-wallet private key into Codex. Never display the key or read the config file into the conversation.
+5. Leave the terminal session running while the user completes approval. The CLI detects approval automatically and saves `HYPERLIQUID_ACCOUNT_ADDRESS` as the master account.
+6. After setup completes, verify the connection with `openbroker account --json` and report the master account address, API signing-wallet address, account mode, and equity without exposing secrets.
+
+If approval times out, preserve the incomplete config and approval URL. Ask the user to finish approval, then rerun `openbroker setup --api-wallet`; the CLI reuses the existing API key and resumes polling instead of generating another wallet.
+
+If a complete config already exists, do not delete or replace it without explicit user approval. Inspect account identity with `openbroker account --json` first.
+
+The interactive `openbroker setup` command still supports three modes, with API wallet as the default when the user presses Enter:
+
+1. **Fresh wallet** — creates a separately funded wallet; builder fee approval is handled automatically.
 2. **Imported key** — use an existing wallet.
-3. **API wallet** — can trade but not withdraw; the human owner must approve it in a browser.
+3. **API wallet (default)** — can trade but not withdraw; the human owner approves it in a browser.
 
 For API wallets, `HYPERLIQUID_PRIVATE_KEY` is the signing key and `HYPERLIQUID_ACCOUNT_ADDRESS` must be the funded master account. If account output shows `$0` equity unexpectedly, check that mapping first.
 
@@ -190,7 +226,6 @@ Bundled examples are **references, not production strategies**. Read them for AP
 - `api.on(...)`, `api.every(...)`, `api.onStart(...)`, `api.onStop(...)`, `api.onError(...)`.
 - `api.state` — persisted state; survives restarts.
 - `api.audit.record(...)` / `api.audit.metric(...)` — durable observability.
-- `api.publish(...)` — notify an OpenClaw agent when hooks are configured.
 - `api.dryRun` — whether writes are intercepted.
 
 Core events include `tick`, `price_change`, `funding_update`, `position_opened`, `position_closed`, `position_changed`, `pnl_threshold`, `margin_warning`, `order_filled`, `order_update`, and `liquidation`.
@@ -223,7 +258,7 @@ These matter more than boilerplate:
 7. **Separate strategy logic from execution policy.** Maker-first execution can reduce fees, but it needs bounded retries, post-only rejection handling, order cancellation, partial-fill accounting, minimum trade thresholds, and a defined IOC fallback. Measure progress from refreshed balances/positions, not only from submit responses.
 8. **Size from real NAV and hard caps.** Multi-leg strategies often need spot balances, spot USDC, and perp account value combined; a 50/50 carry target derived from total NAV must then be halved per side and still respect a hard per-side cap.
 9. **Define stop behavior intentionally.** On shutdown, always handle working orders, but do not blindly flatten every strategy. A hedged carry may need “preserve hedge and alert,” while a transient execution bot may need “cancel and flatten.”
-10. **Instrument first-class decisions.** Log and audit funding source, targets, leg notionals, settlement distance, hold/close decisions, fills, retries, and error paths. If using the plugin, publish events that need human attention.
+10. **Instrument first-class decisions.** Log and audit funding source, targets, leg notionals, settlement distance, hold/close decisions, fills, retries, and error paths. Surface events that need human attention through the configured monitoring path.
 
 Additional practical caveats:
 
@@ -234,34 +269,10 @@ Additional practical caveats:
 - Naked directional positions usually need explicit TP/SL or equivalent risk logic. Hedged multi-leg strategies need strategy-specific exits instead of cargo-cult TP/SL rules.
 - For new automations, do a dry run, inspect `auto report`, and only then run live unless the user explicitly requested immediate live execution.
 
-## Plugin-aware use
-
-When the OpenClaw plugin is available:
-
-- Prefer `ob_*` tools for common structured reads and simple writes.
-- Use `ob_watcher_status` for background monitoring state.
-- Use `ob_auto_run`, `ob_auto_stop`, and `ob_auto_list` for supported automation actions.
-- Fall back to the CLI for unsupported commands, debugging, richer flags, or if a tool returns empty/unexpected data.
-
-Representative mappings:
-
-| Plugin tool | CLI equivalent |
-|---|---|
-| `ob_account` | `openbroker account --json` |
-| `ob_positions` | `openbroker positions --json` |
-| `ob_funding` | `openbroker funding --json --include-hip3` |
-| `ob_search` | `openbroker search --query <QUERY> --json` |
-| `ob_buy` / `ob_sell` | `openbroker buy|sell --coin <COIN> --size <SIZE>` |
-| `ob_limit` | `openbroker limit ...` |
-| `ob_tpsl` | `openbroker tpsl ...` |
-| `ob_auto_run` | `openbroker auto run <script> ...` |
-
-Skill-only mode is fully usable through the CLI; the plugin adds agent tools, watcher notifications, and OpenClaw webhook integration.
-
 ## Failure checks
 
 - `No market data found` → search again; likely wrong venue prefix.
 - `$0` equity on an API wallet → likely missing `HYPERLIQUID_ACCOUNT_ADDRESS`.
 - Unexpected funding behavior → check whether you are reading predicted vs cached instantaneous data.
 - Strategy churn → inspect confirmation loops, fee-aware hold logic, settlement guards, and min-trade thresholds before changing position size.
-- Tool failure in plugin mode → rerun the equivalent CLI command with `--json` and `--verbose` if needed.
+- Unexpected or empty CLI output → rerun the command with `--json` and `--verbose`, then inspect the returned error before retrying a write.

package/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "OpenBroker"
+  short_description: "Trade and automate Hyperliquid from Codex"
+  default_prompt: "Use $openbroker to install OpenBroker and guide me through restricted API-wallet setup."
+
+policy:
+  allow_implicit_invocation: false

package/bin/cli.ts

@@ -11,6 +11,7 @@ const scriptsDir = path.resolve(__dirname, '../scripts');
 
 const commands: Record<string, { script: string; description: string }> = {
   // Setup
+  'install': { script: 'setup/install.ts', description: 'Install OpenBroker for an agent harness' },
   'setup': { script: 'setup/onboard.ts', description: 'Interactive setup wizard' },
   'onboard': { script: 'setup/onboard.ts', description: 'Interactive setup wizard' },
   'approve-builder': { script: 'setup/approve-builder.ts', description: 'Approve builder fee' },
@@ -68,6 +69,7 @@ Open Broker - Hyperliquid Trading CLI
 Usage: openbroker <command> [options]
 
 Setup:
+  install              Install OpenBroker for Codex or another agent harness
   setup                One-command setup (wallet + config + builder approval)
 
 Info Commands:
@@ -136,7 +138,8 @@ Utility:
   approve-builder      Check or retry builder fee approval
 
 Examples:
-  openbroker setup                              # First-time setup (does everything)
+  npx openbroker@latest install --codex        # Install skill + CLI + API-wallet setup
+  openbroker setup --api-wallet                 # Recommended restricted API-wallet setup
   openbroker account                            # View account info
   openbroker buy --coin ETH --size 0.1          # Market buy 0.1 ETH
   openbroker limit --coin BTC --side buy --size 0.01 --price 60000

package/dist/setup/install.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env npx tsx
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/setup/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../scripts/setup/install.ts"],"names":[],"mappings":""}

package/dist/setup/install.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env npx tsx
+// Harness-aware OpenBroker installer.
+import * as fs from 'fs';
+import * as path from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '../..');
+const args = new Set(process.argv.slice(2));
+function printUsage() {
+    console.log(`
+OpenBroker Harness Installer
+============================
+
+Usage:
+  openbroker install --codex [options]
+  npx openbroker@latest install --codex [options]
+
+Harnesses:
+  --codex       Install the OpenBroker skill for Codex
+
+Options:
+  --skip-cli    Do not install the persistent global CLI
+  --skip-setup  Install files without starting API-wallet onboarding
+  --help        Show this help
+
+The default Codex flow installs the global CLI, writes the skill under
+$CODEX_HOME/skills/openbroker (default: ~/.codex/skills/openbroker), and starts
+restricted API-wallet onboarding.
+`);
+}
+function fail(message) {
+    console.error(`Error: ${message}`);
+    process.exit(1);
+}
+function assertOpenBrokerSkill(skillPath) {
+    if (!fs.existsSync(skillPath))
+        return;
+    const existing = fs.readFileSync(skillPath, 'utf8');
+    if (!/^name:\s*openbroker\s*$/m.test(existing)) {
+        fail(`refusing to overwrite unrelated skill at ${skillPath}`);
+    }
+}
+function copyManagedFile(source, destination) {
+    if (!fs.existsSync(source)) {
+        fail(`packaged installer asset is missing: ${source}`);
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 });
+    fs.copyFileSync(source, destination);
+    fs.chmodSync(destination, 0o644);
+}
+function installCodexSkill() {
+    const codexHome = process.env.CODEX_HOME || path.join(homedir(), '.codex');
+    const destination = path.join(codexHome, 'skills', 'openbroker');
+    const skillPath = path.join(destination, 'SKILL.md');
+    assertOpenBrokerSkill(skillPath);
+    copyManagedFile(path.join(packageRoot, 'SKILL.md'), skillPath);
+    copyManagedFile(path.join(packageRoot, 'agents', 'openai.yaml'), path.join(destination, 'agents', 'openai.yaml'));
+    console.log(`✅ Codex skill installed: ${destination}`);
+    return destination;
+}
+function installGlobalCli() {
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    console.log('\nInstalling the persistent OpenBroker CLI...');
+    const result = spawnSync(npmCommand, ['install', '-g', 'openbroker@latest'], {
+        stdio: 'inherit',
+    });
+    if (result.error) {
+        fail(`could not start npm: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        fail('global CLI installation failed. Fix the npm permission error, then rerun with --skip-cli.');
+    }
+}
+function runApiWalletSetup() {
+    const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
+    console.log('\nStarting restricted API-wallet onboarding...\n');
+    const result = spawnSync(process.execPath, ['--import', 'tsx', onboardPath, '--api-wallet'], {
+        stdio: 'inherit',
+        cwd: packageRoot,
+        env: process.env,
+    });
+    if (result.error) {
+        fail(`could not start onboarding: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        fail('API-wallet onboarding did not complete. Rerun `openbroker setup --api-wallet`.');
+    }
+}
+function main() {
+    if (args.has('--help') || args.has('-h')) {
+        printUsage();
+        return;
+    }
+    if (!args.has('--codex')) {
+        printUsage();
+        fail('choose a supported harness flag such as --codex');
+    }
+    console.log('OpenBroker — Codex Installation');
+    console.log('================================\n');
+    installCodexSkill();
+    if (!args.has('--skip-cli')) {
+        installGlobalCli();
+    }
+    if (!args.has('--skip-setup')) {
+        runApiWalletSetup();
+    }
+    console.log('\n✅ OpenBroker installation complete.');
+    console.log('Restart Codex or start a new thread, then invoke $openbroker.');
+}
+main();

package/dist/setup/onboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"onboard.d.ts","sourceRoot":"","sources":["../../scripts/setup/onboard.ts"],"names":[],"mappings":";AA4BA,UAAU,aAAa;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwND,iBAAe,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAsR5C;AAGD,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,CAAC"}
+{"version":3,"file":"onboard.d.ts","sourceRoot":"","sources":["../../scripts/setup/onboard.ts"],"names":[],"mappings":";AA6BA,UAAU,aAAa;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwND,iBAAe,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CA8R5C;AAGD,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,CAAC"}

package/dist/setup/onboard.js

@@ -14,6 +14,7 @@ const GLOBAL_CONFIG_PATH = path.join(GLOBAL_CONFIG_DIR, '.env');
 // Parse CLI flags
 const cliArgs = process.argv.slice(2);
 const useTestnet = cliArgs.includes('--testnet') || ENV_TESTNET;
+const useApiWallet = cliArgs.includes('--api-wallet');
 const accountAddressIdx = cliArgs.indexOf('--account-address');
 const cliAccountAddress = accountAddressIdx !== -1 ? cliArgs[accountAddressIdx + 1] : undefined;
 const configPathIdx = cliArgs.indexOf('-c') !== -1 ? cliArgs.indexOf('-c') : cliArgs.indexOf('--config');
@@ -213,11 +214,13 @@ Usage: openbroker setup [options]
 Options:
   -c, --config <path>       Save config to a custom path (default: ~/.openbroker/.env)
   --testnet                 Configure for testnet
+  --api-wallet              Generate a restricted API wallet and skip the wallet menu
   --account-address <addr>  Set HYPERLIQUID_ACCOUNT_ADDRESS (for API wallet / vault trading)
   --help                    Show this help
 
 Examples:
-  openbroker setup                                                    # Interactive → ~/.openbroker/.env
+  openbroker setup                                                    # Interactive; API wallet is the default
+  openbroker setup --api-wallet                                       # Recommended agent setup
   openbroker setup -c .env --testnet                                  # Write to ./.env for testnet
   openbroker setup -c ./testnet.env --testnet --account-address 0x... # API wallet config
 `);
@@ -300,21 +303,26 @@ Examples:
             walletAddress: account.address,
         };
     }
+    // Agent-friendly non-interactive selection. Browser approval is still
+    // deliberately completed by the human who controls the master wallet.
+    if (useApiWallet) {
+        return setupApiWallet();
+    }
     // Ask user which setup mode
     const rl = createReadline();
     console.log('Step 1/3: Wallet Setup');
     console.log('----------------------');
     console.log('How would you like to set up your wallet?\n');
-    console.log('  1) Generate a fresh wallet (recommended for agents)');
-    console.log('     Creates a dedicated trading wallet. Builder fee is auto-approved.');
-    console.log('     Just fund it with USDC and start trading — no browser steps needed.');
+    console.log('  1) Generate a fresh wallet');
+    console.log('     Creates a dedicated funded wallet. Builder fee is auto-approved.');
     console.log('');
     console.log('  2) Import existing private key');
-    console.log('  3) Generate API wallet (restricted, requires browser approval)');
+    console.log('  3) Generate API wallet (recommended for agents)');
     console.log('     Can trade but cannot withdraw. Requires master wallet approval in browser.\n');
     let choice = '';
     while (choice !== '1' && choice !== '2' && choice !== '3') {
-        choice = await prompt(rl, 'Enter choice (1, 2, or 3): ');
+        const input = await prompt(rl, 'Enter choice (1, 2, or 3) [3]: ');
+        choice = input || '3';
         if (choice !== '1' && choice !== '2' && choice !== '3') {
             console.log('Please enter 1, 2, or 3');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "dist/",
     "scripts/",
     "config/example.env",
+    "agents/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md"

package/scripts/setup/install.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env npx tsx
+// Harness-aware OpenBroker installer.
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '../..');
+const args = new Set(process.argv.slice(2));
+
+function printUsage(): void {
+  console.log(`
+OpenBroker Harness Installer
+============================
+
+Usage:
+  openbroker install --codex [options]
+  npx openbroker@latest install --codex [options]
+
+Harnesses:
+  --codex       Install the OpenBroker skill for Codex
+
+Options:
+  --skip-cli    Do not install the persistent global CLI
+  --skip-setup  Install files without starting API-wallet onboarding
+  --help        Show this help
+
+The default Codex flow installs the global CLI, writes the skill under
+$CODEX_HOME/skills/openbroker (default: ~/.codex/skills/openbroker), and starts
+restricted API-wallet onboarding.
+`);
+}
+
+function fail(message: string): never {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function assertOpenBrokerSkill(skillPath: string): void {
+  if (!fs.existsSync(skillPath)) return;
+
+  const existing = fs.readFileSync(skillPath, 'utf8');
+  if (!/^name:\s*openbroker\s*$/m.test(existing)) {
+    fail(`refusing to overwrite unrelated skill at ${skillPath}`);
+  }
+}
+
+function copyManagedFile(source: string, destination: string): void {
+  if (!fs.existsSync(source)) {
+    fail(`packaged installer asset is missing: ${source}`);
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 });
+  fs.copyFileSync(source, destination);
+  fs.chmodSync(destination, 0o644);
+}
+
+function installCodexSkill(): string {
+  const codexHome = process.env.CODEX_HOME || path.join(homedir(), '.codex');
+  const destination = path.join(codexHome, 'skills', 'openbroker');
+  const skillPath = path.join(destination, 'SKILL.md');
+
+  assertOpenBrokerSkill(skillPath);
+  copyManagedFile(path.join(packageRoot, 'SKILL.md'), skillPath);
+  copyManagedFile(
+    path.join(packageRoot, 'agents', 'openai.yaml'),
+    path.join(destination, 'agents', 'openai.yaml'),
+  );
+
+  console.log(`✅ Codex skill installed: ${destination}`);
+  return destination;
+}
+
+function installGlobalCli(): void {
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  console.log('\nInstalling the persistent OpenBroker CLI...');
+  const result = spawnSync(npmCommand, ['install', '-g', 'openbroker@latest'], {
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    fail(`could not start npm: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(
+      'global CLI installation failed. Fix the npm permission error, then rerun with --skip-cli.',
+    );
+  }
+}
+
+function runApiWalletSetup(): void {
+  const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
+
+  console.log('\nStarting restricted API-wallet onboarding...\n');
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', onboardPath, '--api-wallet'],
+    {
+      stdio: 'inherit',
+      cwd: packageRoot,
+      env: process.env,
+    },
+  );
+
+  if (result.error) {
+    fail(`could not start onboarding: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail('API-wallet onboarding did not complete. Rerun `openbroker setup --api-wallet`.');
+  }
+}
+
+function main(): void {
+  if (args.has('--help') || args.has('-h')) {
+    printUsage();
+    return;
+  }
+
+  if (!args.has('--codex')) {
+    printUsage();
+    fail('choose a supported harness flag such as --codex');
+  }
+
+  console.log('OpenBroker — Codex Installation');
+  console.log('================================\n');
+
+  installCodexSkill();
+
+  if (!args.has('--skip-cli')) {
+    installGlobalCli();
+  }
+
+  if (!args.has('--skip-setup')) {
+    runApiWalletSetup();
+  }
+
+  console.log('\n✅ OpenBroker installation complete.');
+  console.log('Restart Codex or start a new thread, then invoke $openbroker.');
+}
+
+main();

package/scripts/setup/onboard.ts

@@ -18,6 +18,7 @@ const GLOBAL_CONFIG_PATH = path.join(GLOBAL_CONFIG_DIR, '.env');
 // Parse CLI flags
 const cliArgs = process.argv.slice(2);
 const useTestnet = cliArgs.includes('--testnet') || ENV_TESTNET;
+const useApiWallet = cliArgs.includes('--api-wallet');
 const accountAddressIdx = cliArgs.indexOf('--account-address');
 const cliAccountAddress = accountAddressIdx !== -1 ? cliArgs[accountAddressIdx + 1] : undefined;
 const configPathIdx = cliArgs.indexOf('-c') !== -1 ? cliArgs.indexOf('-c') : cliArgs.indexOf('--config');
@@ -257,11 +258,13 @@ Usage: openbroker setup [options]
 Options:
   -c, --config <path>       Save config to a custom path (default: ~/.openbroker/.env)
   --testnet                 Configure for testnet
+  --api-wallet              Generate a restricted API wallet and skip the wallet menu
   --account-address <addr>  Set HYPERLIQUID_ACCOUNT_ADDRESS (for API wallet / vault trading)
   --help                    Show this help
 
 Examples:
-  openbroker setup                                                    # Interactive → ~/.openbroker/.env
+  openbroker setup                                                    # Interactive; API wallet is the default
+  openbroker setup --api-wallet                                       # Recommended agent setup
   openbroker setup -c .env --testnet                                  # Write to ./.env for testnet
   openbroker setup -c ./testnet.env --testnet --account-address 0x... # API wallet config
 `);
@@ -358,23 +361,29 @@ Examples:
     };
   }
 
+  // Agent-friendly non-interactive selection. Browser approval is still
+  // deliberately completed by the human who controls the master wallet.
+  if (useApiWallet) {
+    return setupApiWallet();
+  }
+
   // Ask user which setup mode
   const rl = createReadline();
 
   console.log('Step 1/3: Wallet Setup');
   console.log('----------------------');
   console.log('How would you like to set up your wallet?\n');
-  console.log('  1) Generate a fresh wallet (recommended for agents)');
-  console.log('     Creates a dedicated trading wallet. Builder fee is auto-approved.');
-  console.log('     Just fund it with USDC and start trading — no browser steps needed.');
+  console.log('  1) Generate a fresh wallet');
+  console.log('     Creates a dedicated funded wallet. Builder fee is auto-approved.');
   console.log('');
   console.log('  2) Import existing private key');
-  console.log('  3) Generate API wallet (restricted, requires browser approval)');
+  console.log('  3) Generate API wallet (recommended for agents)');
   console.log('     Can trade but cannot withdraw. Requires master wallet approval in browser.\n');
 
   let choice = '';
   while (choice !== '1' && choice !== '2' && choice !== '3') {
-    choice = await prompt(rl, 'Enter choice (1, 2, or 3): ');
+    const input = await prompt(rl, 'Enter choice (1, 2, or 3) [3]: ');
+    choice = input || '3';
     if (choice !== '1' && choice !== '2' && choice !== '3') {
       console.log('Please enter 1, 2, or 3');
     }