OpenClaw Shell Completion: Enable Tab Autocomplete in Bash, Zsh & Fish

Every experienced OpenClaw user has shell completion enabled. It's not optional once you've used it — typing openclaw ga and hitting Tab to get openclaw gateway instantly, or seeing a list of your registered channels when you Tab after openclaw channel send, changes how you use the CLI entirely. The setup takes two minutes. Here it is for every major shell.

What OpenClaw Completion Covers

The completion system covers more than just subcommand names. As of early 2025, OpenClaw's completion script handles:

• Subcommands — gateway, agent, channel, skill, memory, logs, completion, update, version
• Flags and options — every flag for every subcommand, including shorthand aliases
• Config file paths — file path completion for --config flags
• Dynamic values — when connected to a running gateway, completes registered channel IDs and skill names

The dynamic completion is the most valuable part. Instead of looking up your Telegram channel ID, you tab-complete it from the list of registered channels. This alone justifies the setup time.

Bash Completion Setup

First, verify bash-completion is installed:

# Ubuntu/Debian
sudo apt install bash-completion

# macOS (Homebrew)
brew install bash-completion@2

# Alpine
apk add bash-completion

Generate and install the completion script:

# Option 1: Append to .bashrc (simplest)
openclaw completion bash >> ~/.bashrc
source ~/.bashrc

# Option 2: System-wide installation (for all users)
openclaw completion bash | sudo tee /etc/bash_completion.d/openclaw > /dev/null

Test it:

openclaw [Tab][Tab]

You should see a list of available subcommands. If nothing happens, bash-completion may not be loading. Check that your ~/.bashrc sources the bash-completion package:

# Add this to ~/.bashrc if not present
if [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
fi

Zsh Completion Setup

Zsh uses fpath to find completion files. The cleanest approach creates a dedicated directory:

# Create completions directory
mkdir -p ~/.zsh/completions

# Generate completion file
openclaw completion zsh > ~/.zsh/completions/_openclaw

Add these lines to your ~/.zshrc (before any compinit call):

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

Apply immediately:

source ~/.zshrc

Oh-My-Zsh Users

Oh-my-zsh manages its own completion loading. Place the file where it can find it:

openclaw completion zsh > ~/.oh-my-zsh/completions/_openclaw

No changes to .zshrc needed — oh-my-zsh loads completions from that directory automatically. Restart your terminal to activate.

Fish Completion Setup

Fish is the easiest of the three. One command:

openclaw completion fish > ~/.config/fish/completions/openclaw.fish

Fish auto-loads completions from that directory. No profile edits, no sourcing — it works immediately in new fish sessions. To activate in the current session:

source ~/.config/fish/completions/openclaw.fish

Test with Tab:

openclaw [Tab]

Fish shows completions inline with descriptions — much more informative than bash or zsh's default completion display.

macOS-Specific Notes

macOS users running zsh (the default since Catalina) should verify that compinit is called in their .zshrc. macOS's default .zshrc is often empty, which means completions never load.

For Homebrew-installed tools, the completion files land in $(brew --prefix)/share/zsh/site-functions/. Add this to your fpath:

fpath=($(brew --prefix)/share/zsh/site-functions $fpath)
autoload -Uz compinit
compinit

Then install the OpenClaw completion into the same location:

openclaw completion zsh > $(brew --prefix)/share/zsh/site-functions/_openclaw

Troubleshooting Completion

Completion not working? Work through this checklist:

1. Did you source the profile? Run source ~/.bashrc or source ~/.zshrc after setup — changes don't apply to the current session automatically.
2. Is bash-completion installed? Run type _init_completion in bash — if it returns "not found", install bash-completion.
3. Is the completion script correct? Run openclaw completion bash (no redirect) and verify the output starts with # bash completion for openclaw.
4. Is the file in the right location? For zsh, run echo $fpath and verify your completions directory is listed.
5. Did you update OpenClaw recently? Regenerate the completion script after updates — the script content changes when new commands are added.

Common Mistakes

• Using > instead of >> for bash — single redirect overwrites .bashrc entirely; use append (>>) when adding to existing profile files
• Not installing bash-completion — sourcing the completion script does nothing without the underlying bash-completion framework
• Placing zsh completion file in wrong location — must be in a directory on fpath and must be named _openclaw (leading underscore)
• Forgetting to regenerate after updates — new OpenClaw versions add new commands and flags; the cached completion script won't know about them
• Using the wrong shell's completion script — bash and zsh scripts are not interchangeable; always generate for the shell you're actually running

Frequently Asked Questions

How do I enable OpenClaw tab completion in bash?

Run: openclaw completion bash >> ~/.bashrc && source ~/.bashrc. This appends the bash completion script to your profile and activates it immediately. You'll need bash-completion installed on your system — on Ubuntu/Debian: sudo apt install bash-completion, on macOS: brew install bash-completion.

How do I set up OpenClaw completion in zsh?

Run: openclaw completion zsh > ~/.zsh/_openclaw. Then add fpath=(~/.zsh $fpath) and autoload -Uz compinit && compinit to your ~/.zshrc. Restart your shell or run source ~/.zshrc. If you use oh-my-zsh, place the completion file in ~/.oh-my-zsh/completions/ instead.

Does OpenClaw shell completion work on macOS?

Yes, on both bash and zsh. macOS ships with an old bash (3.2) that has limited completion support — install a newer bash via Homebrew for best results. Zsh completion works perfectly with macOS's default zsh. Fish completion also works on macOS after installing fish via Homebrew.

What commands does OpenClaw shell completion autocomplete?

Shell completion covers all top-level subcommands (gateway, agent, channel, skill, memory, logs), all flags and options for each subcommand, and dynamic values like registered channel names and skill identifiers when connected to a running gateway. Tab twice to see all available options at any point.

Why isn't OpenClaw completion working after I set it up?

Common causes: you didn't source the updated profile (run source ~/.bashrc or restart the shell), bash-completion is not installed on your system, or the completion script was written to the wrong location. Run openclaw completion bash to print the script and verify its contents look correct.

Can I get OpenClaw completion in fish shell?

Yes. Run: openclaw completion fish > ~/.config/fish/completions/openclaw.fish. Fish loads completions automatically from that directory — no additional configuration needed. Restart fish or run source ~/.config/fish/completions/openclaw.fish to activate immediately.