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. claude CLI, gemini CLI)

---

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:

1. Choose your platform — Telegram, Discord, or Slack

2. Enter your bot token — paste the token you created above

3. Validate the token — confirms it can reach the platform API

4. Detect agents — scans your system for installed ACP-compatible agents

5. Set your workspace — the directory your agents will have access to

6. 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.ts when 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:

1. Loaded your config from ~/.openacp/config.json

2. Connected your bot to the chat platform

3. Started listening for messages

When you sent /new, OpenACP:

1. Created a new Session for you

2. Spawned an AgentInstance — a subprocess running your AI agent via ACP

3. 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