OpenACP is self-hosted so the user and developer are the same person. Consolidated into one unified quickstart page with a natural flow: Install → Setup wizard → Start → Chat. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.1 KiB
Quick Start
This guide gets you from zero to chatting with an AI agent in your Telegram (or Discord, or Slack) in about ten minutes.
What you'll need
- Node.js 20 or later — check with
node --version - A bot token for your chat platform:
- Telegram: create one via @BotFather
- Discord: create one in the Discord Developer Portal
- Slack: create one at api.slack.com/apps
- An ACP-compatible agent installed on your machine (e.g.
claudeCLI,geminiCLI)
Step 1: Install OpenACP
npm install -g @openacp/cli
Verify it installed:
openacp --version
Step 2: Run the setup wizard
openacp
The first time you run openacp, it detects there's no config and launches an interactive setup wizard that walks you through:
- Choose your platform — Telegram, Discord, or Slack
- Enter your bot token — paste the token you created above
- Validate the token — confirms it can reach the platform API
- Detect agents — scans your system for installed ACP-compatible agents
- Set your workspace — the directory your agents will have access to
- Choose run mode — foreground (for testing) or daemon (runs in background)
Most prompts have sensible defaults — just press Enter to accept them.
Step 3: Start OpenACP
If you chose foreground mode:
openacp start
If you chose daemon mode, it started automatically. Check with:
openacp status
Step 4: Chat with your AI agent
Open the Telegram group (or Discord server, or Slack channel) linked to your bot and send:
/new
OpenACP creates a session — a dedicated thread between you and an AI agent. On Telegram this becomes a forum topic, on Discord and Slack a thread.
Now send a real message:
What files are in the src/ directory?
You should see:
- Streaming text — the agent's response arrives piece by piece in real time
- Tool calls — status updates like
🔧 Running: read_file src/main.tswhen the agent reads files or runs commands - Permission requests — some actions show Approve / Deny buttons and wait for your response
- Auto-naming — the session topic gets renamed based on your first message
Step 5: Useful commands
| Command | What it does |
|---|---|
/new |
Start a new session with a fresh agent |
/cancel |
Stop the current response |
/status |
Check the status of your active session |
/menu |
Open the action menu |
For the full list, see Chat Commands.
What just happened?
When you ran openacp start, OpenACP:
- Loaded your config from
~/.openacp/config.json - Connected your bot to the chat platform
- Started listening for messages
When you sent /new, OpenACP:
- Created a new Session for you
- Spawned an AgentInstance — a subprocess running your AI agent via ACP
- Routed your message to the agent and streamed the response back to chat
Your data directory
Everything OpenACP stores lives in ~/.openacp/:
| Path | What's in it |
|---|---|
config.json |
Your configuration (bot token, agent, allowed users) |
sessions.json |
Active and recent session metadata |
usage.json |
Token and cost tracking |
logs/ |
Application logs |
files/ |
Files shared through the chat |
plugins/ |
Installed plugins |
To reconfigure at any time:
openacp onboard
Next steps
- Platform setup — detailed guides for Telegram, Discord, and Slack
- Configuration — all config options explained
- Agents — configure and switch between agents
- Daemon Mode — running OpenACP as a background service
- Voice & Speech — voice messages and audio responses