Content
<p align="center">
<img src="./imgs/openocta_logo.png" alt="OpenOcta" width="420">
</p>
<p align="center">
<b>OpenOcta</b> —— Open-source Enterprise AI Agent; Single binary, deploy anywhere, quick to use, and integrate with enterprises.
</p>
> [English](README.en.md) |
OpenOcta is **completely self-developed** as a **single Go binary backend + embedded frontend**, suitable for intelligent dialogue, process automation, and integration with business systems, APIs, and toolchains within enterprises.
**Welcome to submit PRs or share good ideas for this project**
---
## Project Introduction
- **Positioning**: Provide a unified **AI Agent runtime and control surface** within enterprises, which can access business systems, HTTP/API, MCP tools, and custom skills, supporting dialogue, task orchestration, and automation integration.
- **Form**: A single binary containing Gateway, Agent, Channels, Cron, and frontend static resources, which can be connected to external systems via CLI, HTTP/WebSocket, Webhook, etc.
---
## Communication and Feedback
- **Discussion and Experience Sharing**: Welcome to join the OpenOcta discussion group to exchange deployment practices, integration scenarios, and best practices.
- **Issue Feedback and Demand Suggestions**: You can ask questions or feedback usage issues in the group, and you're also welcome to submit Issues/PRs in the Git repository.
<p align="center">
<img src="./imgs/wechat.png" alt="OpenOcta Discussion Group QR Code" width="220" height="220">
<br/>
<sub>Scan the QR code to join the OpenOcta discussion group for the latest updates and support</sub>
</p>
---
## Quick Start
### Environment Requirements
- **Go 1.24+** (for building the backend)
- **Node ≥18** (only required for compiling the frontend during build, not needed in production)
- Environment variable **`ANTHROPIC_API_KEY`** (required when using the `agent` command)
### Build and Start Gateway
```bash
# Build (recommended using Makefile)
make build
# Or use the script
./build.sh build # Supports: ui | embed | go | build | clean | snapshot | release | docker
# Start Gateway
make run
# Or
./openocta gateway run
```
The Gateway listens on `http://127.0.0.1:18900` by default, with HTTP and WebSocket sharing the same port. The **frontend is embedded in the binary using go:embed**, so you can access the Control UI directly through a browser.
### Development Mode (Frontend Hot Update)
```bash
# Terminal 1: Run Gateway (need to build once)
./openocta gateway run
# Terminal 2: Run Frontend Dev Server (port 5173)
make run-ui
```
Access `http://localhost:5173` in your browser to debug the frontend.
### Use Agent CLI
```bash
export ANTHROPIC_API_KEY=your-key
./openocta agent -m "Hello, echo test"
```
### Configuration File
When running for the first time and the configuration file does not exist, it will automatically initialize from the embedded `openocta.json.example` and write it to the configuration directory:
| Platform | Default Configuration Directory |
|---------------|------------------------------------------|
| Linux / macOS | `~/.openocta/openocta.json` |
| Windows | `%APPDATA%\openocta\openocta.json` |
### macOS Desktop Installation (.dmg)
- **`.dmg`**: The mounted path is in **`/Volumes/...`** (read-only image), drag the application to «Applications» or install it to **`/Applications/OpenOcta.app`** as prompted; **do not** treat the contents under `/Volumes` as an installed copy, and **eject** the disk image in Finder. See `deploy/dist-README.md` for details.
---
## Documentation and References
### Document Language Mapping
- **English Docs**
- Root: `README.en.md`
### Main Documents
- **Backend Overview**: `src/README.md`
Module description, migration status, and backend-related documentation index.
- **Frontend Description**: `ui/README.md`
Control UI feature introduction, development scripts, and directory structure.
- **Configuration and Capabilities** (located in `src/docs/`):
- `configuration.md` — Configuration overview: agents, channels, gateway, cron, hooks, memory, etc.
- `mcp-configuration.md` — MCP server declaration and permissions, timeout configuration.
- `request-tracing.md` — Request tracing, token usage, and call chain recording.
- `webhooks.md` — Request/response structure and applicable scenarios for `/hooks/wake`, `/hooks/agent`, `/hooks/alert`.
- `architecture.md` — Layered design and extension points based on agentsdk-go.
- `skills.md`, `tools.md`, `tools-builtin.md`, `tools-openocta.md` — Overall description of the skills and tool systems.
Upstream References:
- [OpenClaw Official Repository](https://github.com/openclaw/openclaw)
- [docs.openclaw.ai](https://docs.openclaw.ai) (including official documentation for Gateway protocol, configuration, etc.)
---
## Project Structure
```text
OpenOcta/
├── src/ # Go backend (Gateway, Agent, Channels, Cron, etc.)
│ ├── cmd/openocta/ # CLI entry and subcommands
│ ├── embed/ # Embedded resources (frontend, config-schema, openocta.json.example)
│ │ └── frontend/ # Frontend build output (generated by build)
│ ├── pkg/ # Core modules
│ └── README.md # Detailed backend description
├── ui/ # Control UI frontend (Lit + Vite, WebSocket control surface)
│ └── README.md # Detailed frontend description
├── deploy/ # Deployment-related (Dockerfile, systemd service, scenario templates, etc.)
└── docs/ # Documentation and migration plan
```
- **Backend**: Go 1.24+, providing Gateway HTTP + WebSocket, Agent, Channels, Cron, Config, and other capabilities.
- **Frontend**: Control UI is embedded in a single binary using **go:embed**, and the frontend does not need to be deployed separately in production.
- **Single Binary**: The built `openocta` contains the frontend and configuration template, which can be directly distributed and run.
---
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=openocta/openocta&type=Date&legend=top-left&theme=dark&token=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">
<a href="https://www.star-history.com/#openocta/openocta&Date">
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=openocta/openocta&type=Date&legend=top-left&token=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">
</a>
</picture>
## Copyright Notice
This repository follows the **GPLv3** open-source license.
You can develop secondary products based on OpenOcta's source code, but you need to comply with the following regulations:
- You cannot replace or modify OpenOcta's logo and copyright information;
- Derivative works developed secondarily must comply with the open-source obligations of GPLv3.
For commercial authorization, please contact: **sales@databuff.com**.
