Ai Keeper/ Manual/ Reference & FAQ
Reference and FAQ

Look something up. Then fix what broke.

This page is the lookup layer: every slash command, every provider route, and troubleshooting sorted by the symptom you can actually see. For click-by-click instructions, use the step-by-step guides instead.

Looking for the old numbered recipes? They were replaced by the full workflow library292 walkthroughs with prerequisites, numbered steps, a verification check, and per-symptom fixes. The six recipes that used to live here are now First steps, APIs and clients, Knowledge and RAG, Agents and workspaces, Automation, and Channels.

Where the walkthroughs are

Every task that used to be summarised here now has a full walkthrough with prerequisites, numbered steps, a way to check it worked, and fixes for the things that usually go wrong.

Slash Command Dictionary

Slash commands are shortcuts you type in chat starting with /. Type /commands in the Chat to see a live list with autocomplete.

The current 66 built-in commands are registered by SlashCommandHandler. The groups below cover the full set; custom commands installed by skills, plugins, or ClawHub packages appear alongside them in /commands. Matching is case-insensitive.

Session control

Manage the conversation: /new, /clear, /reset, /stop, /regenerate, /compact, /export-session, /import-session — start over, stop a response, regenerate, summarize, export, or import a saved JSON conversation.

Lifecycle and persistence controls for the active session: clear context, reset agent state, stop generation, regenerate last response, force-trigger compaction, export Markdown/JSON, or import supported JSON.

Model and reasoning

Change how the AI responds: /models, /think, /reasoning, /fast, /verbose, /elevated — see what models are available, turn on slow careful thinking, or switch between quick / detailed / expert reply styles.

List runnable/running models, toggle thinking mode, show step-by-step reasoning, or switch response modes (fast, verbose, elevated/expert).

Status and identity

"What's going on right now?": /status, /context, /session, /whoami, /id, /usage — show running models, what the AI's seeing in this chat, who you are, and how much you've spent.

Inspect active model and tasks, effective prompt and policies for the current agent, session/thread binding, identity and channel info, and runtime usage/limits.

Composition shortcuts

One-click prompts and side questions: /summarize, /translate, /code, /explain, /fix, /review, /brainstorm, /proscons, /side, /btw — pre-shape the next turn or ask a side question without interrupting the main task.

Single-shot prompt templates plus two aliases for a side-question turn. Useful before piping a paragraph, snippet, or attached file.

Memory and knowledge

What the AI knows about you: /memory — see the saved facts. Edit them in Knowledge > Memory.

Inspect the assistant's stored memory facts. Extract policy and per-fact controls live under Knowledge > Memory.

Document ingestion

Index and maintain local sources: /ingest, /ingested, /forget, /watch, /unwatch — add a file/folder, list indexed sources, remove matching sources, or start/stop folder watching.

Shortcuts into the Documents ingestion and watched-folder pipeline. Use /ingested to verify state before relying on retrieval.

Tools and capabilities

What tools/extensions are available: /tools, /commands, /plugins, /mcp, /hooks, /orders, /tasks — list everything the AI can use right now.

List active-agent tools, all slash commands, installed ClawHub packages, connected MCP servers, active hooks, standing orders, and scheduled tasks.

Discovery and safeguards

Find capabilities and protect work: /find, /recommend, /snapshot, /rollback — search Skills/MCP, surface capability gaps, snapshot a directory, or restore the latest snapshot.

Registry discovery and workspace recovery controls for tool-assisted sessions. A snapshot is a safety checkpoint, not a replacement for a normal backup.

Commitments and chat presets

Track follow-ups and reuse chat setup: /commitments, /commit, /preset — list inferred commitments, add one manually, or save/apply/list per-chat configuration presets.

Conversation-level follow-up tracking and reusable chat configuration, separate from the app-wide Work Modes hub.

Agent operations

Multi-agent control: /agent, /agents, /subagents, /focus, /unfocus, /steer, /queue, /kill — turn agent mode on, hand off to another agent, focus on one task, or stop a runaway agent.

Toggle agent mode, manage agents and sub-agents, focus/unfocus a task, redirect to another agent or mode, switch queue mode, or terminate a session.

Approvals and execution

Granting and limiting power: /approve, /exec, /acp, /allowlist, /activation — say yes/no to pending tool approvals, run a shell command, or change who's allowed to DM the assistant.

Resolve pending exec/tool approvals, configure exec policy or run a shell command, edit ACP policies, manage DM/channel allowlists, or change channel activation policy.

Channels and voice

Outbound and live audio: /send messages another channel, /vc manages voice chat, /restart restarts what's running.

/send targets a channel; /vc shows or manages voice-channel status; /restart restarts the active runtime or connector.

Removed in this revision because they are not registered: /model (use /models), /config, /help. /vc is voice-channel control, not version control.

Provider Guide

Local

Models running on your own Mac. Free, private, works offline.

Local instances for privacy, offline operation, or predictable cost. Tune context and output limits to fit RAM.

CLI providers

For Claude Code and ChatGPT Codex — they sign in through their own desktop apps, not with a regular API key.

CLI-based agent providers. Auth is handled by the provider's installed binary rather than an API key route.

Cloud APIs

Pay another company (OpenAI, Anthropic, Google, etc.) to run a model for you. Need an API key from them.

Available routes: ChatGPT Codex, Claude Code, OpenAI, Anthropic, Google Gemini, Groq, Mistral, DeepSeek, xAI, OpenRouter, Together AI, Perplexity, Fireworks AI, Cerebras, Lemonade, and Custom. The two CLI routes use their installed authentication; Lemonade and Custom can point at local or remote OpenAI-compatible servers.

Failover

A backup plan: if one provider stops working (rate-limited, slow, down), the app tries the next one automatically.

Failover chains trip on rate-limit, auth failure, latency, or downtime. Key rotation distributes load across multiple keys.

Context caps

Some cloud providers limit how much you can send/receive in one go, even if you set a higher number. The app respects their limit automatically.

Provider-enforced max prompt+output windows. Ai Keeper clamps to the smaller of the user-configured value or the provider's metadata cap.

Cost

Cloud models cost money per use. Check the Usage screen to see what you've spent. Use local models for routine stuff to save money.

Track token consumption and cost trends in System > Usage. Use local models for high-volume routine work; reserve cloud providers for quality- or capability-sensitive tasks.

Troubleshooting FAQ

Model will not start

Run System > Health first. Then switch the backend back to Automatic and remove any custom command-line flags. Most "won't start" issues are missing dependencies or a bad flag.

Check System > Health (Diagnostics + Doctor), instance diagnostics, System > Logs, dependency status, model format vs. backend choice, custom args, and port conflicts. Use Automatic backend and clear custom args to reduce variables.

Proxy returns errors

Make sure at least one instance is running and that whatever app is calling Ai Keeper is using the proxy URL (the one that ends in /v1).

Verify a ready instance, proxy enabled, route exists, API key correct, client targeting the proxy base URL. Inspect endpoint/status/latency in System > Requests.

Responses are too short

Bump up the max output tokens setting. Also check if you accidentally turned on /fast mode, which keeps replies brief.

Increase max output tokens; check for active fast/terse modes; inspect stop sequences and structured-output constraints.

Responses are repetitive

The AI is stuck in a loop. Try raising the Repetition Penalty in settings. Don't go too high or it'll start dropping necessary words.

Increase repetition penalty; adjust frequency/presence penalties for loops. For code, avoid excessive penalties — they break required syntax. Lower temperature only if randomness is the actual issue.

Tool calls fail

The AI tried to use a tool but couldn't. Type /tools to see what's actually available, then check if you've approved the tool and whether the right model family is selected.

Audit tool policy, parser, model family alignment, MCP server state, approval queue, and per-surface web/tool-execution permissions. Use /tools, the MCP tabs, and request logs.

RAG answers miss facts

Search for the fact in Documents or Wiki first. If it is there, check Wiki Health: stale snapshots, deleted sources, and broken current-truth pointers are deliberately withheld instead of being returned as current facts.

Separate indexing from eligibility before tuning ranking. Verify an Embedding-role runtime and manual search; run Wiki Health lint; resolve missing dates, stale observations, invalid pointers, and retired/deleted sources. Only then tune Top-K or chunk size/overlap and re-index the affected corpus.

Wiki says freshness review is needed

Open the affected claim and check its source. Re-observe it if it is still true, point it at a reliable current source, or retire it if it should no longer be used.

Knowledge > Wiki > Health reports volatile claims without time semantics, snapshots without dates, observations older than their freshness window, and unresolved pointers. Use Re-observe now, Use source pointer, or Retire; each correction preserves the prior revision.

Obsidian write-back is stopped

The original note changed after Ai Keeper last read it. Reconcile the vault, compare the newer note with your Wiki edit, then try again only after deciding which content should win.

Write-back compares the current note hash with the last imported source hash and fails closed on a mismatch. Use Reconcile Wiki Now or wait for Watch and schedule, review the refreshed page, and make a new deliberate edit; do not bypass the conflict check.

App uses too much memory

Stop any models you're not using right now. Don't keep three big models warm if you only need one.

Stop unused instances, lower context window, reduce cache budgets, enable KV cache quantization, lower idle threshold, or enable auto-unload on critical pressure.

Automations act unexpectedly

Pause it. Open the Audit Trail to see what it actually did. Re-test the same task manually before turning it back on.

Pause the job, inspect Audit Trail, review standing orders/hooks, check workspace safety settings, require approvals for external side effects. Prototype manually before re-enabling.

Channels do not receive messages

A connector (Slack, Telegram, etc.) isn't getting messages. Check that the connector is on, the URL/token is right, and look at Channel Health.

Verify connector enabled state, transport, webhook URL, verify token, server URL, workspace/channel IDs, and Channel Health Monitor state. Cross-check inbound traffic in shared Inbox.

Remote client cannot connect

Another Mac can't reach this one. Make sure Server mode is on, the API key matches, and your firewall isn't blocking the port.

Confirm Server mode, management URL, Allow Client Access toggle, matching API key, firewall/network reachability, and port. Keep Web Tool Execution off unless explicitly required.

AI·KEEPER MANUAL · LOCAL BY DEFAULT · macOS 14+ · APPLE SILICON
← aikeeper.app