AgentOctopus

Use when you need to route a user query to the best specialized skill — AgentOctopus semantically matches queries against installed skills, executes the top...

Intelligent skill router. Give it a natural language query; it embeds the query, scores against available skills (cosine similarity + quality ratings), LLM re-ranks the top candidates, executes the best match, and returns the result. No matching skill → direct LLM answer.

All interaction is through the octopus CLI.

Quick start

octopus onboard              # one-time interactive setup (LLM config, skills, API keys)
octopus ask "what's the weather in Tokyo?"

On first run, octopus ask auto-triggers onboarding if no config exists.

Commands

Routing

octopus ask <query>          # route a query to the best skill
  --debug                    # show embedding, scoring, and timing internals
  --no-prompt                # skip the interactive feedback prompt

octopus ask loads the registry, builds the embedding index, routes the query, executes the matched skill, and prints the result. It tries up to 3 candidate skills before falling back to a direct LLM answer.

Skill management

octopus list                 # list installed skills with star ratings and invocation counts
octopus sync                 # interactive: sync skills from ClawHub, ratings from GitHub Gist
  --cloud-url <url>          # sync from a cloud AgentOctopus instance
  --category <name>          # install only skills from one category
  --check                    # show available updates without installing
  --force                    # overwrite existing skills
  --dry-run                  # preview without changes
  --ratings                  # sync ratings specifically
  --pull                     # pull ratings from cloud (shorthand)
  --push                     # push ratings to cloud (shorthand)
octopus search <query>       # search ClawHub (remote) for skills, not local
octopus add <slug>           # install a skill from ClawHub
  --version <version>        # install a specific version
  --force                    # overwrite existing skill
octopus remove <name>        # remove an installed skill
octopus update               # check and install latest @agentoctopus npm packages
  --check                    # show updates without installing (exits code 1 if updates exist)
  -y, --yes                  # skip confirmation prompt

octopus sync without flags runs interactively (prompts: skills, ratings, or both). octopus sync --check checks for skill updates on ClawHub. octopus update --check checks for AgentOctopus package updates on npm — these are different things.

After installing or removing skills, restart the gateway server to pick up changes.

Setup & configuration

octopus onboard              # interactive setup wizard (LLM provider, model, embed, API keys)
octopus connect openclaw     # import LLM config from an existing OpenClaw installation
octopus config set <key> <value>  # save a credential to ~/.agentoctopus/.env
octopus config list          # show resolved configuration (keys masked)
octopus start                # start the gateway server on port 3002

Config is stored in ~/.agentoctopus/octopus.json with secrets in ~/.agentoctopus/.env.

How routing works

Query → Embedding index → Cosine similarity + keyword boost → LLM re-rank → Execute → Result

1. Embedding index — each skill's name and description is embedded. The query is embedded against this index.
2. Cosine similarity + keyword boost — skills are scored; ineligible skills (wrong OS, missing binaries, missing env vars) are filtered out.
3. LLM re-rank — top candidates are sent to the chat LLM with "none" as a valid answer. If the LLM returns "none", no skill runs.
4. Execute — the best skill is executed via the appropriate adapter (subprocess, HTTP, or MCP, inferred from the skill directory). On failure, the next candidate is tried (up to maxRetries, default 3).
5. Fallback — if all candidates fail or no skill matches, the query is answered directly by the chat LLM.

Error handling

Credential missing

When a skill requires an API key that isn't configured:

1. AgentOctopus detects the missing key from the skill's frontmatter
2. Generates a setup guide showing how to obtain and configure the key
3. Tries the next candidate skill
4. If all candidates fail due to missing keys, falls back to direct LLM answer

octopus config set OPENAI_API_KEY sk-abc123...

Binary missing

When a skill requires a CLI tool that isn't installed:

1. AgentOctopus lists the missing binaries
2. Shows install instructions
3. Tries the next candidate skill

Execution failure

If a skill's adapter returns an error, AgentOctopus prints the error and tries the next candidate. Use --debug to see full error details.

Common failure patterns and fixes:

Error pattern	Cause	Fix
Permission denied + scripts/ path	Script file missing execute bit	chmod +x ~/.agentoctopus/skills/<name>/scripts/*
uses local scripts	HTTP-adapter skill that needs local scripts	octopus add <name> --force

Sessions

The HTTP API (/agent/ask) supports sessions via sessionId — pass the ID from the first response in follow-up requests for conversation continuity. Sessions expire after 30 minutes of inactivity and keep the last 50 messages.

The CLI octopus ask is stateless per invocation and does not use sessions.

Node.js usage

import { createAgentRouter } from '@agentoctopus/gateway';
import express from 'express';

const app = express();
const agentRouter = await createAgentRouter('/path/to/AgentOctopus');
app.use('/agent', agentRouter);
app.listen(3002);

The gateway exposes these endpoints:

Endpoint	Auth	Purpose
POST /agent/ask	Required	Route a query
POST /agent/feedback	Required	Submit thumbs up/down
GET /agent/health	Public	Liveness check
POST /agent/register	Public	Self-service API key registration
GET /agent/skills	Required	List installed skills
POST /agent/sync	Required	Trigger skill sync from cloud

POST /agent/ask request body:

{
  "query": "what is the weather in Tokyo",
  "agentId": "my-agent",
  "sessionId": "optional-session-id",
  "metadata": {}
}

• query (required) — natural language query
• agentId (optional) — identifier for the calling agent
• sessionId (optional) — continue an existing session
• metadata (optional) — arbitrary JSON merged into the session

Response shapes: success: true with skill + response, success: true with skill: null (LLM fallback), or success: false with type: "credential_missing" or type: "binary_missing".

For direct engine access without Express:

import { bootstrapEngine, DIRECT_ANSWER_SYSTEM_PROMPT } from '@agentoctopus/gateway';

const engine = await bootstrapEngine('/path/to/AgentOctopus');
const [routing] = await engine.router.route("weather Tokyo");
if (routing) {
  const result = await engine.executor.execute(routing.skill, { query: "weather Tokyo" });
  console.log(result);
} else {
  const answer = await engine.chatClient.chat(DIRECT_ANSWER_SYSTEM_PROMPT, "weather Tokyo");
  console.log(answer);
}

Common workflows

Initial setup:

octopus connect openclaw    # pull in existing LLM config
octopus sync                # install skills from ClawHub

Daily use:

octopus ask "translate 'hello' to Japanese"
octopus ask "what's the weather in London?"

Keeping skills fresh:

octopus sync --check        # see what's available
octopus sync                # install updates
octopus update --check      # check for AgentOctopus itself

Finding and adding skills:

octopus search "github"          # find GitHub-related skills
octopus add github-issue-viewer  # install one
octopus list                     # verify it's installed