0xmrpeter 7007ed3cec docs(gitbook): write all 8 content sections — complete documentation
Sections written:
- Getting Started (what-is-openacp, for-users, for-developers, for-contributors)
- Platform Setup (Telegram, Discord, Slack)
- Using OpenACP (commands, sessions, agents, permissions, voice, files)
- Self-Hosting (installation, configuration, daemon, security, logging, updating)
- Features (tunnel, context-resume, usage, persistence, handoff, doctor, assistant)
- Extending (plugin-system, building-adapters, adapter-reference, contributing)
- API Reference (CLI commands, REST API, config schema, env vars)
- Troubleshooting (Telegram, Discord, Slack, agent issues, FAQ)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 18:00:11 +07:00

2.4 KiB

Doctor

What it is

openacp doctor runs a suite of system health checks and reports the status of every major component. It is the fastest way to diagnose why something is not working — misconfigured tokens, missing agent binaries, stale PID files, corrupt sessions data, and more.


Running doctor

From the terminal:

openacp doctor

From inside Telegram or Discord, send /doctor in the Assistant topic.

Each check produces one or more results with a status of pass, warn, or fail. A summary line at the end shows total counts.


Checks

Check What it verifies
Config Config file exists, is valid JSON, passes schema validation, and has no pending migrations
Agents Each configured agent's binary exists on PATH; flags a missing default agent as a failure
Telegram Bot token is set, the bot can reach the Telegram API, and the configured chat ID resolves to a supergroup with forum topics enabled
Discord Bot token and guild ID are set, the bot can connect and access the configured guild
Storage ~/.openacp/ directory exists and is writable; sessions.json is valid; log directory exists and is writable
Workspace The configured workspace.baseDir exists and is readable
Plugins Plugins directory exists; each installed plugin can be loaded without errors
Daemon PID file is valid and the process is alive; API port file is valid; API port is in use by OpenACP (not another process)
Tunnel Tunnel is enabled; configured provider is recognized; cloudflared binary is present (for Cloudflare provider); tunnel port is in valid range

Auto-fix

Some issues can be fixed automatically. When a fix is marked as safe (low risk), doctor applies it immediately and reports what was done. Examples of safe auto-fixes:

  • Applying pending config migrations
  • Removing a stale or invalid PID file
  • Removing an invalid API port file
  • Creating a missing log directory
  • Installing the cloudflared binary

Fixes that are risky (could cause data loss, such as resetting a corrupt sessions file) are listed as pending and require explicit confirmation before they are applied.


Exit code

openacp doctor exits with code 0 if all checks pass or produce only warnings. It exits with code 1 if any check fails. This makes it usable in CI or startup scripts:

openacp doctor || exit 1