OpenOPC: Build Your Personal AI-Native Company — Self-Built, Self-Run, Self-Grown

English | 简体中文

🏗️ **Self-Built** — Fully automated to recruit role-specific AI employees and build the org. ⚙️ **Self-Run** — Fully automated to assign tasks, drive handoffs, and keep moving toward your goal. 🌱 **Self-Grown** — Learns from every task, builds organizational memory, always delivers smarter.

Python 3.10+ Office UI CLI and UI License MIT Feishu WeChat

![OpenOPC hero banner](docs/assets/chat.png) ## News - **Sep 3, 2026 — JiuwenSwarm compatibility update:** Setup now uses the verified JiuwenSwarm `0.2.4b4` and openJiuwen `0.1.16` versions. - **Sep 1, 2026 — A more responsive Office UI:** Office and developer-tool rendering are now isolated from high-frequency runtime events, reducing unnecessary full-app updates and keeping Workspace and Org views smoother during long-running sessions. - **Aug 26, 2026 — JiuwenSwarm integration:** Use JiuwenSwarm-single as a single agent or JiuwenSwarm-team as one opaque Team in both Task and Company modes — a self-organizing swarm that plugs into your org seamlessly. [Setup and role behavior](#jiuwen-integration). - **Jul 14, 2026 — More resilient company runs:** Company-mode sessions now recover and resume more seamlessly while preserving agent identity, shared role context, delegation, and review progress. - **Jul 13, 2026 — Smoother Office UI:** Faster live updates and chat scrolling improve long-running projects. - **Jul 8, 2026 — Smarter approvals:** Session grants persist, low-risk actions flow automatically, and deferred decisions stay available. ## Table Of Contents - [When To Use OpenOPC](#when-to-use-openopc) - [Demos](#demos) - [How OpenOPC Works](#how-openopc-works) - [Quick Start](#quick-start) - [Office UI Guide](#office-ui-guide) - [CLI Guide](#cli-guide) - [Configuration](#configuration) - [JiuwenSwarm](#jiuwen-integration) - [Ecosystem And Sharing](#ecosystem-and-sharing) - [Roadmap](#roadmap) - [Acknowledgements](#acknowledgements) ## When to Use OpenOPC **OpenOPC** covers nine core verticals — from AI development and software engineering to finance, sales, media, e-commerce, and education. Whatever the industry, OpenOPC assembles the right team and delivers end-to-end.

🤖 AI Tech & Research
Model training & evaluation, Agent development, LLM apps & AI infrastructure
💻 Software Development
Android apps, SaaS MVPs, websites, mini programs & game development
📈 Financial Investment
Investment memos, market maps, due diligence & IC decision packages
🚀 Sales Growth
Outbound sales, deal strategy, proposals & channel expansion 		🎬 Content & Media
Video production, short-form content, scripts, storyboards & multi-platform cuts 		🤝 Industry Assistants
Copilots for support, real estate, legal intake, HR onboarding, retail
🧾 Accounting & Finance
Bookkeeping, financial reporting, tax compliance, budgeting & risk review 		🛍️ Brand & E-commerce
Brand planning, product selection, store ops, user growth & retention 		🎓 Education & Training
Curriculum design, knowledge base, learner management & content production
## Demos
OpenOPC video production demo

🎬 Video Production 		OpenOPC VC investment research demo

📈 Investment Research 		OpenOPC game prototype demo

🎮 Game Prototype
## How OpenOPC Works OpenOPC assembles a AI company around complex, real-world tasks — through three tightly coupled mechanisms: **Self-Built** staffs the organisation, **Self-Run** executes the work, and **Self-Grown** learns from the outcome.

An OpenOPC company: roles, reporting lines, and the employee staffed into each role

**1. Self-Built — Staffing the Organisation** Before any work begins, the right people must be in place. Given a goal, OpenOPC: - 🌿 Drafts the org chart — deriving the roles and reporting structure the task demands. - 🎯 Fills each role — a recruiter agent chooses between reusing an existing employee (shaped by prior projects) and onboarding a fresh hire from the talent pool. 💡 Experienced employees carry accumulated context; fresh hires offer a clean slate when a role demands it. **⚙️ 2. Self-Run — Executing the Work** With the team assembled, Self-Run orchestrates its members toward a finished deliverable. The central challenge is not raw execution but efficient collaboration under uncertainty, which manifests in two distinct problems. 🔀 Dynamic collaboration orchestration. Real work cannot be fully planned upfront. OpenOPC addresses this through a work-item state machine, where each item's phase determines: - 📋 Its kanban column — where it stands in the workflow. - 👑 Its owner — the role responsible at that phase. - ✅ Its runnability — whether it is ready to proceed. A manager decomposes items, assigns, and reviews results — accepting, reworking, or escalating — across five modes: execute, delegate, review, integrate, and rework. Decomposition defines a dependency DAG, so: - ⚡ Independent items proceed in parallel. - ⏳ Dependent items wait until prerequisites are resolved. 🔗 Dependency resolution and rejection propagate as structured phase transitions, eliminating ad-hoc coordination. 🛡️ Handling blockers surfacing mid-run. Not all obstacles are visible upfront. OpenOPC resolves them at two levels: - 💬 Within the team — a blocking message pauses the sender, activating the role best positioned to resolve it. - 📡 Beyond the team — when a blocker exceeds the team's authority, the runtime escalates to the human owner, invoking human judgment precisely when needed. 🖥️ The kanban and office views render this orchestration in real time. **🌱 3. Self-Grown — Learning from the Run** Execution generates raw experience; Self-Grown turns it into lasting improvement, guided by two principles. 🏅 Attributing outcomes to the right roles. Crediting the whole company teaches nothing. Instead, OpenOPC: - 🔍 Resolves user feedback into per-employee evaluations. - 🎯 Updates only roles that owned the relevant work items — credit and blame land where they were earned. 📖 Distilling trajectories into knowledge. Execution traces are too noisy to learn from. OpenOPC therefore: - 💡 Distils each role's tasks into high-signal lessons, stored in its private experience profile. - 📚 Promotes recurring lessons into shared playbooks, which new hires inherit from the outset — compounding organisational knowledge over time.
How this maps to the UI - `Org -> Team` edits the company architecture and roles. - `Org -> Employees` hires talent into vacant roles. - `Team Roster -> Deploy` turns a hired employee into a visible office agent. - The Workspace composer selects the Task Mode execution agent. - The role inspector can set runtime policy and preferred external agent for Company Mode roles. - During execution, Workspace `Agents` and the Execution Progress panel show which role is active, which work item it owns, and which execution agent is doing the concrete work.
## Quick Start `uv` is the recommended setup path for OpenOPC. It can install/manage Python, create the project virtualenv, and run commands against that environment without mixing OpenOPC dependencies into your global Python. OpenOPC requires Python `>=3.10`; the examples below use Python `3.12`. For direct one-off work, OpenOPC also includes Task Mode, a LobeChat-like single-agent workspace using OpenOPC Native, Codex, Claude Code, Cursor, or OpenCode.
Recommended: uv environment setup **macOS** ```bash # Install uv with Homebrew, or use the official standalone installer. brew install uv # curl -LsSf https://astral.sh/uv/install.sh | sh cd /path/to/OpenOPC uv python install 3.12 uv venv --python 3.12 source .venv/bin/activate ``` **Linux** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh source "$HOME/.local/bin/env" cd /path/to/OpenOPC uv python install 3.12 uv venv --python 3.12 source .venv/bin/activate ``` **Windows PowerShell** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" cd C:\path\to\OpenOPC uv python install 3.12 uv venv --python 3.12 .\.venv\Scripts\Activate.ps1 ``` **Windows Command Prompt** ```bat winget install --id=astral-sh.uv -e :: Or run the standalone installer from cmd: :: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" cd C:\path\to\OpenOPC uv python install 3.12 uv venv --python 3.12 .venv\Scripts\activate.bat ```
```bash # Install OpenOPC into the uv-managed environment uv pip install -e . # Optional but recommended for browser tools uv run python -m playwright install chromium # Initialize local config, memory, skills, projects, and workspace folders uv run opc init # Add an API key in .opc/config/llm_config.yaml # or configure the env var named by llm.api_key_env. # Launch the browser UI uv run opc ui ``` Open `http://localhost:8765` by default. ```bash # Interactive CLI uv run opc chat -p demo # One-shot task mode uv run opc chat -p demo --mode task --agent codex "Refactor this module and run focused tests" # Company mode with the built-in Corporate architecture uv run opc chat -p demo --mode company --company-profile corporate "Plan, implement, review, and document this feature" # Non-interactive scripting / CI style usage uv run opc exec -p demo --mode task --agent native --json "Summarize the current repo status" ```
Install notes - Python: `>=3.10`. Current required dependencies do not all publish Python 3.9-compatible releases. - `uv` is recommended for local development and release testing. If you prefer classic pip, create and activate a Python `>=3.10` virtualenv, then run `python -m pip install -e .`. - If virtualenv activation is blocked, stay unactivated and run commands with `uv run ...`. - See the official [`uv` installation](https://docs.astral.sh/uv/getting-started/installation/) and [Python management](https://docs.astral.sh/uv/guides/install-python/) docs for alternative package managers and managed Python details. - Node.js: `>=18` is needed when the Office UI frontend must be built. - `opc ui` auto-installs missing `aiohttp` / `aiosqlite` and auto-builds the frontend if needed. - If you have not installed external agent CLIs yet, run `opc init --no-external-agent-preflight` to skip the first-run external-agent checks. - Browser tools are native Playwright tools. Install Chromium with `python -m playwright install chromium` before asking agents to browse pages.
Development setup (build from source) ```bash python -m pip install -e . python -m pytest cd opc/plugins/office_ui/frontend_src npm install npm run typecheck npm run build ``` The frontend build output is served from `opc/plugins/office_ui/frontend_dist/`.
## Office UI Guide
Expand the Office UI guide — visual tour, workspace, company mode, kanban, office, org Start it with: ```bash opc ui opc ui --port 9000 --project demo opc ui --rebuild ``` ### Visual Tour Scroll horizontally to browse the Office UI walkthrough. Each screenshot keeps its short guide text attached.
Workspace project, chat, mode, organization, and agent controls
Workspace And Setup. Choose or create a project, start New Chat, then select Company or Task plus the matching organization or agent. In Company Mode, pick role employees and execution agents, or let OpenOPC auto-recruit.
Execution Progress panel showing role status and execution records
Execution Progress. Track every role's state, then click a role or work item to inspect detailed execution records, tool activity, handoffs, reviews, and runtime metadata.
Kanban board showing agent work items and status
Kanban. Supervise each agent's concrete tasks and work items as they move through planning, execution, review, blockers, and completion.
Organization editor for tuning existing organizations and creating new ones
Org Control. Tune existing organizations, adjust roles and reporting lines, review runtime policy, or create a new organization.
Talent market for browsing and recruiting employees
Talent Market. Browse talent templates, inspect candidate details, and recruit employees into vacant roles when the company needs more capability.
Animated office view showing what each role is doing
Office View. Watch the organization as an animated office, with each role/agent showing status, current task, active tool, seat, and runtime activity.
The Office UI has three primary pages: | Page | What you do there | |---|---| | **Workspace** | Main working surface: session list, kanban board, chat, task details, role progress, comms, and team cockpit. | | **Office** | Visual office map: agents appear as characters, can be selected, moved, assigned to seats, and inspected. | | **Org** | Company architecture: switch corporate/saved orgs, create new organizations, edit roles, hire talent, apply architecture presets, and import/export configs. | ### Workspace The Workspace page is the default screen. | Area | What to look for | |---|---| | Left sidebar | Project sessions, activity, unread counts, and new chat creation. | | Center board | Kanban cards. In Task Mode, a card is normally one task-backed chat session. In Company Mode, the board follows the selected runtime session and shows delegated work items. | | Right panel | Context panel with tabs such as `Chat`, `Agents`, `Info`, `Comms`, and `Team`. Collapse, resize, or maximize it while work is running. | | Composer | Send messages, attach files, choose mode, choose company architecture, and in Task Mode choose the execution agent. | ### Start Work From The UI 1. Create or select a project from the top project selector. 2. In Workspace, click `New Chat`. 3. In the composer, choose `Task` or `Company`. 4. For Task Mode, choose the agent: `OpenOPC Native`, `Codex`, `Claude Code`, `Cursor`, or `OpenCode`. 5. For Company Mode, choose `Corporate` or a saved org architecture. 6. Send the brief. Once the first message is sent, the mode and task agent are locked for that chat. Use the locked-mode popover to continue in a new chat with a different mode. ### Company Mode In The UI Company Mode turns one brief into a runtime session plus role-owned work items. | Tab | What it shows | |---|---| | `Chat` | Parent conversation, final responses, runtime progress cards, checkpoint replies, stop/continue/done controls, and links into work-item execution. | | `Agents` | Role rollup: active/waiting/pending/done roles, current tool, role work items, filters, search, and links to detailed execution progress. | | `Info` | Status, assignees, role identity, employee assignment, selected execution agent, timing, and developer details. | | `Comms` | Role inboxes, unread/read/sent messages, meetings, decisions, and recent communication failures. | | `Team` | Runtime cockpit: teams, seats, approvals, unread communication, run state, and stop controls for the current run. | To inspect the detailed workflow for a role, open a company-mode session and click a role/work item in the `Chat` progress card or `Agents` tab. The Execution Progress panel shows each work item, its status, activity sections, tool progress, handoffs, review targets, and execution turn metadata. ### Kanban - Task Mode: the kanban is a project-level board. You can quick-create tasks in `Todo`, start them, and inspect each task from the right panel. - Company Mode: the active board follows the selected runtime session. Cards represent company work items and move from planning/execution/review/done according to backend runtime state. - Manual drag between status columns is intentionally restricted when runtime owns the state. Same-column reorder is supported where applicable. ### Office Use the Office page when you want a visual view of the running team. - Click an agent character or row to inspect status, current tool, current task, role, office, and seat. - Use the office/seat controls to move an agent. - Sub-agents can be shown or hidden. - Agents created from employees or templates appear in the office and are persisted in `.opc/ui_state.db`. ### Org The Org page is where company structure becomes runnable. | Sub-tab | Purpose | |---|---| | `Team` | View/edit the role graph, table, role inspector, roster, saved org selector, export package flow, and deploy hired employees to the office. | | `Runtime` | Tune runtime teams, seats, final decider, delegation strategy, and runtime policy. Corporate is read-only; saved orgs are editable. | | `Architecture` | Browse built-in architecture presets, preview/apply packages, manage installed packages, and import/export YAML. | | `Employees` | Search talent templates, view details, hire into vacant roles, and staff the company. | To create a new company: open `Org`, click `New organization`, enter a name, add at least two members with responsibilities and reporting lines, review, and create. OpenOPC saves it automatically and switches the composer to `Company / `. To recruit: import talent templates first, then open `Org -> Employees`, search a template, click `Hire`, choose a vacant role, and deploy the employee from `Team Roster` if you want it visible in the Office page. ```bash opc talent import /path/to/agency-agents ```
Where project files live OpenOPC separates runtime/config state from deliverable workspace files. | Path | Meaning | |---|---| | `.opc/config/` | Local config copied from `config/` by `opc init`. | | `.opc/memory/` | Global and project markdown memory. | | `.opc/projects//` | Project runtime metadata and task stores. | | `.opc/ui_state.db` | Office UI chat, channels, and visual agent state. | | `../OpenOPC_workplace//` | Default project workplace. Agents should write durable project files here. | | `../OpenOPC_workplace//.opc-comms/` | Internal company-mode comms mailboxes, meetings, and tool-result scratch space. | Set `OPC_HOME=/path/to/opc-home` if you want config and runtime state outside the repo.
## CLI Guide
Expand the CLI guide — common commands and interactive slash commands OpenOPC exposes both high-level natural-language commands and lower-level UI/service commands. Conceptually OpenOPC has two execution modes: `task` and `company`. Some lower-level CLI/service commands still expose `org` as a compatibility selector for Company Mode with a saved organization architecture; in the UI this appears as Company plus an architecture choice. ### Common Commands ```bash # Chat opc chat opc chat -p demo --mode task --agent native "Inspect the failing tests" opc chat -p demo --mode company --company-profile corporate "Ship this change with review" # Scriptable execution opc exec -p demo --mode task --agent codex --stream-json "Run the migration check" opc exec -p demo --mode company --company-profile corporate "Draft the research report" # Project lifecycle opc project list opc project create demo opc project switch demo # Sessions opc session list -p demo opc session create "New feature" -p demo --mode company opc session send "Continue with implementation" -p demo opc session stop -p demo opc session continue "Proceed after review" -p demo # Runtime inspection opc runtime status -p demo opc runtime logs -p demo opc work-item list -p demo opc work-item show -p demo opc comms state -p demo # Recruitment opc talent import /path/to/agency-agents opc talent hire -p demo ``` ### Interactive Slash Commands Run `opc chat`, then use slash commands: ```text /status /mode task /mode company corporate /agent codex /project switch demo /session list /runtime --full /logs --full /comms --full /org /talent list /market list ``` See [`docs/cli-chat-slash.md`](docs/cli-chat-slash.md) for the full command table.
CLI command groups | Group | Examples | |---|---| | `opc project` | `list`, `show`, `create`, `switch`, `rename`, `delete --yes` | | `opc session` | `list`, `create`, `show`, `config`, `send`, `rename`, `delete --yes`, `stop`, `continue`, `resume`, `complete` | | `opc mode` | `show`, `set task`, `set company --profile corporate`, `set org --org ` for a saved-org company run | | `opc kanban` | `view`, `task create`, `task update`, `task move`, `task assign`, `task status`, `task delete --yes` | | `opc agent` | `list`, `create`, `create-from-template`, `import-employee`, `detail`, `move`, `delete --yes` | | `opc org` | `info`, `export`, `import`, `saved list/save/load/delete`, `role add/update/bulk-add/delete`, `policy update`, `strategy update`, `reset --yes` | | `opc talent` | `list`, `employees`, `import`, `hire`, `scan`, `import-selected`, `employee-detail`, `import-agent` | | `opc market` | `presets`, `browse`, `preview`, `apply-preset`, `export`, `install`, `list`, `uninstall --yes` | | `opc runtime` | `status`, `checkpoints`, `logs`, `run` | | `opc permissions` | Show the Native default, or `set read-only|auto|full-access` for new sessions | | `opc channels` | `status`, `login`, `start`, `stop` | Most service-style commands accept `--project/-p` and `--json`. For saved organization architectures, some CLI/service commands currently use `org` as a compatibility selector even though the conceptual runtime is still Company Mode: ```bash opc exec -p demo --mode org --org hku_research_lab "Draft the research report" opc session create "Research sprint" -p demo --mode org --org hku_research_lab ```
## Configuration Run `opc init` once from the repo root. It creates `.opc/`, copies the template config from `config/`, creates memory/skills/log folders, and optionally creates the first project. Project-local `.opc/config` files can select local executables, remote endpoints, and credential sources. OpenOPC therefore asks for workspace trust before loading an existing project's config; non-interactive commands fail closed. Review the files, then use `opc trust add /path/to/workspace`. Trust is bound to fingerprints of the security-relevant source files and their normalized effective authority, so changes to system, LLM, agent, or channel configuration require renewal. Legacy path-only records also require one renewal. Use `opc trust list` and `opc trust remove /path/to/workspace` to inspect or revoke the user-owned decision. A workspace initialized by `opc init` is trusted automatically at creation time.
JiuwenSwarm setup and role behavior — JiuwenSwarm OpenOPC exposes two choices in both Task and Company modes: - **JiuwenSwarm-single** is a single external agent, like Codex or Claude Code. It handles only the selected task or role. Its compatible OpenOPC agent ID is `jiuwen`. - **JiuwenSwarm-team** is one opaque external Team. OpenOPC works with the Team as a whole and does not manage its internal agents. Its compatible OpenOPC agent ID is `jiuwenswarm`. ### Setup JiuwenSwarm reads `~/.jiuwenswarm/config/.env`; it does not automatically read OpenOPC's `.opc/config/llm_config.yaml`. You may reuse the same provider credentials, but the model name must support JiuwenSwarm agent requests. For example, Volcengine Ark Agent Plan uses: ```dotenv API_BASE="https://ark.cn-beijing.volces.com/api/plan/v3" API_KEY="" MODEL_NAME="ark-code-latest" MODEL_PROVIDER="OpenAI" ``` JiuwenSwarm requires Python 3.11–3.13. Install the verified JiuwenSwarm `0.2.4b4` / openJiuwen `0.1.16` combination and the OpenOPC Gateway adapter from the OpenOPC repository root. macOS / Linux: ```bash python -m pip install -e ".[jiuwen]" uv tool install --force --python 3.12 \ --overrides docs/jiuwen-openjiuwen-overrides.txt \ "https://github.com/openJiuwen-ai/jiuwenswarm/archive/ec305b70bf4a82f3603ea1a7b3ddc212386662df.tar.gz" jiuwenswarm-init chmod 600 ~/.jiuwenswarm/config/.env jiuwenswarm-start app opc agents preflight jiuwen opc agents preflight jiuwenswarm opc exec --mode task --agent jiuwen "Handle this task" opc exec --mode task --agent jiuwenswarm "Have one Team handle this task" ``` Windows PowerShell / Command Prompt (no `chmod` step): ```powershell py -3.12 -m pip install -e ".[jiuwen]" uv tool install --force --python 3.12 ` --overrides docs/jiuwen-openjiuwen-overrides.txt ` "https://github.com/openJiuwen-ai/jiuwenswarm/archive/ec305b70bf4a82f3603ea1a7b3ddc212386662df.tar.gz" jiuwenswarm-init jiuwenswarm-start app opc agents preflight jiuwen opc agents preflight jiuwenswarm ``` `jiuwenswarm-start app` stays in the foreground; keep that terminal open while using OpenOPC. On Windows the Jiuwen configuration is normally stored under `%USERPROFILE%\.jiuwenswarm\config\.env`; on macOS/Linux it is under `~/.jiuwenswarm/config/.env`. OpenOPC reads Jiuwen's persisted custom Gateway port, so both sides continue to use the same endpoint. Set `JIUWENSWARM_GATEWAY_URL` or a non-default `gateway_url` in `.opc/config/agent_config.yaml` only for an intentional remote/custom endpoint. OpenOPC supports JiuwenSwarm-single and JiuwenSwarm-team in both Task and Company modes on Windows, macOS, and Linux. Company communication uses the same protected workspace boundary on every platform: POSIX directory handles on macOS/Linux and native handle-relative, reparse-point-safe access on Windows. Windows workspaces must be local; UNC/network-share workspaces fail closed because they cannot provide the same boundary guarantees. ### Role selection in Company Mode Choose the execution agent in Staffing / Recruitment Review, or under **Company → Org → role → Runtime**. - Select **JiuwenSwarm-single** on CTO: only CTO uses JiuwenSwarm-single. CTO's subordinates remain separate OpenOPC roles and keep their own staffing and agent choices. - Select **JiuwenSwarm-team** on CTO: CTO and every role below CTO become one Team. The roles remain visible in the org chart, but descendant controls are locked and OpenOPC does not recruit or assign employees inside that subtree. CEO delegates to the CTO Team boundary and receives one Team result. - Select **JiuwenSwarm-team** on CEO: CEO and the entire company subtree become one Team. Descendants cannot select separate agents or create nested Teams. - Select Teams on several peer managers, such as COO, CTO, and CMO: they become separate Teams coordinated and reviewed by their parent manager. - Select no Team: normal Company staffing and per-role execution continue unchanged. The parent manager receives a capability summary compiled from the covered roles, skills, tools, and deliverables. JiuwenSwarm-team decides how work is divided internally. ### Team Activity (read-only) When JiuwenSwarm-team emits its official Team events, **Execution Progress** still shows one organizational node and one OpenOPC WorkItem executor. Its second line summarizes the observed internal run, for example `3 members · 2 active · Leader synthesizing`. Select that node to open **Team Activity**: Read-only JiuwenSwarm Team Activity drawer showing the leader and three observed internal members - **Overview** shows the leader and only the internal members Jiuwen actually created. OpenOPC covered roles are listed separately and never become inferred members. - **Tasks** is a read-only internal Kanban; **Timeline** shows official member, task, message, retry, completion, and error events; **Output** keeps member outputs separate from the leader synthesis. - `todo_create`, `task_tool`, `covered_role_ids`, and natural-language claims never create Team rows. Team telemetry never creates an OpenOPC Agent, Session, WorkItem, or main Kanban card, and never changes WorkItem progress, review, permissions, or scheduling. - Task and Company modes use the same view. Stored telemetry survives refresh/reconnect and is isolated by project, OpenOPC task, and concrete external invocation. Older runs without structured events say that internal telemetry is unavailable instead of guessing. This view observes Jiuwen's existing `/tui` stream only. It does not modify the Jiuwen harness or open another control connection.
Expand configuration — config files, LLM keys, external agents, channels, browser/MCP, troubleshooting | File | Purpose | |---|---| | `.opc/config/llm_config.yaml` | Default model, LiteLLM/OpenRouter-compatible API base, API key, env var indirection, routing, fallback, temperature, token limit. | | `.opc/config/system_config.yaml` | Runtime behavior, browser tools, native runtime, compaction, verification, permissions, sandbox, and safety settings. | | `.opc/config/agent_config.yaml` | External agent command paths, preferred order, model flags, session modes, timeouts, approval modes, and native subagent profiles. | | `.opc/config/channel_config.yaml` | External messaging providers and credentials. Inbound sender lists are deny-by-default. | | `.opc/config/company_corporate_config.yaml` | Built-in corporate company architecture template. | | `.opc/config/company_orgs/org__config.yaml` | Saved custom company architectures used by Company Mode. | | `.opc/config/org_index.yaml` | Active saved company architecture selector. | ### LLM Keys After `opc init`, edit `.opc/config/llm_config.yaml` in the repo-local OPC home. If you set `OPC_HOME`, edit `$OPC_HOME/config/llm_config.yaml` instead. The template leaves secrets empty. Write your key directly into the file: ```yaml llm: default_model: "openai/gpt-5.4" api_base: "https://openrouter.ai/api/v1" api_key: "sk-or-v1-..." # your OpenRouter (or other provider) API key max_tokens: 32768 # max output tokens per request; lower it if your # model's output cap is smaller # context_window: 128000 # total input window. Usually auto-detected via # litellm; unmapped models fall back to 128000. # Uncomment and set only when the fallback is # wrong for your model. ``` Then verify with `opc status`. If you prefer not to store the key in the file, leave `api_key` empty and set `api_key_env` to the name of an environment variable that holds it (e.g. `api_key_env: "OPENROUTER_API_KEY"`). ### Approval & Agent Permissions OpenOPC Native has three permission levels. Set the default copied into each new session in `.opc/config/system_config.yaml`: ```yaml autonomy: native_approval_level: auto # read-only | auto | full-access ``` | Level | Runs automatically | Asks first | Sandbox | |---|---|---|---| | `read-only` | Local reads and side-effect-free internal tools | Writes, processes that may write, network, external effects, and outside access | Read-only, offline | | `auto` | Reads, workspace edits, commands, and tests | Network, workspace-external access/effects, and explicit safety rules | Workspace-write, offline | | `full-access` | All registered Native tools | No Native tool approval prompts | Off | Use the **Permissions** selector beside Mode/Agent in the UI, including while a session is running. Changes take effect at the next tool call; already-open approval requests are not replayed or auto-approved. The same setting is available from the CLI: ```bash opc permissions opc permissions set auto opc chat --approval-level read-only opc exec --approval-level full-access "Run the task" opc session config --approval-level auto ``` Interactive chat supports `/permissions` and `/permissions read-only|auto|full-access`; `opc status` and `/status` show the effective level and sandbox. A new session freezes the current default. Native subagents and all Native Company roles inherit the root session level, while different projects and sessions remain isolated. Changing the default through the UI or `opc permissions set` atomically refreshes the trust fingerprint of an already trusted workspace. If you edit `.opc/config/*.yaml` by hand, review the change and run `opc trust add ` as usual. When a call asks, approval cards retain once/session/project/global scopes; no grant can override an explicit deny. **Default** in the UI changes only future sessions. `full-access` bypasses only Native tool permission prompts. Organization reviews, hiring decisions, user questions, Company WorkItem gates, controller ownership, durable effect fences, and explicit deny rules remain active. **This setting does not control Codex, Claude Code, JiuwenSwarm-single, JiuwenSwarm-team, or any other external harness; their approval and sandbox settings remain independent.** Legacy Native risk settings are read once for migration, then `native_approval_level` is authoritative. ### External Agents Task Mode can explicitly select an execution agent: ```bash opc chat -p demo --mode task --agent codex "Implement the change" ``` Available values are `native`, `codex`, `claude_code`, `cursor`, `opencode`, `jiuwen` (JiuwenSwarm-single), and `jiuwenswarm` (JiuwenSwarm-team). See [JiuwenSwarm setup and role behavior](#jiuwen-integration). ### Feishu Connection ```bash pip install -e .[channels-feishu] opc init opc channels login feishu ``` Edit `.opc/config/channel_config.yaml`: ```yaml channels: feishu: enabled: true app_id: "cli_xxx" app_secret: "..." encrypt_key: "" verification_token: "" react_emoji: THUMBSUP allow_from: - "ou_xxx" ``` Then: ```bash opc channels status opc channels start -p demo # or run the long-lived engine + channel runtime: opc run -p demo ``` Feishu uses the `lark-oapi` WebSocket client. `app_id` and `app_secret` are required; `encrypt_key` and `verification_token` are optional unless your tenant/app configuration requires them. Keep `allow_from` explicit; an empty list denies all inbound messages.
Other channel providers | Provider | Install extra | Runtime | Required fields | |---|---|---|---| | Telegram | `channels-telegram` | polling | `token` | | Slack | `channels-slack` | socket | `bot_token`, `app_token` | | Discord | `channels-discord` | socket | `token` | | DingTalk | `channels-dingtalk` | socket | `client_id`, `client_secret` | | Email | `channels-email` | polling | IMAP/SMTP fields, `consent_granted` | | Matrix | `channels-matrix` | sync/polling | `homeserver`, `access_token`, `user_id` | | QQ | `channels-qq` | socket | `app_id`, `secret` | | WhatsApp | `channels-whatsapp` | bridge | `bridge_url` | | Mochat | `channels-mochat` | bridge | `base_url`, `claw_token`, `agent_user_id` | Useful commands: ```bash opc channels login slack opc channels status opc channels start -p demo opc channels stop opc run -p demo ``` See [`docs/channels.md`](docs/channels.md) and [`docs/channel-bridges.md`](docs/channel-bridges.md).
Browser tools and MCP servers Browser tools: ```bash python -m playwright install chromium ``` Configure launch behavior in `.opc/config/system_config.yaml`: ```yaml system: browser: mode: embedded # embedded | chrome | auto headless: true chrome_channel: chrome user_data_dir: "" ``` Native browser tools include `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_wait_for`, `browser_scroll`, `browser_select_option`, `browser_evaluate`, `browser_take_screenshot`, and `browser_close`. MCP servers can be added under `mcp_servers` in `system_config.yaml`. Local servers use stdio commands; remote servers use HTTP/SSE-style URLs. Discovered tools are registered with a server prefix to avoid collisions.
### Troubleshooting
Office UI does not open or looks stale ```bash opc ui --rebuild ``` If the browser still shows stale UI state, hard refresh the page. If a previous process died mid-run, restart `opc ui` first so in-memory locks are released.
A task appears stuck Start with a server restart and browser hard refresh. If persisted task state is still dirty, use the reset helper: ```bash python scripts/reset_stuck_task.py --project --session --apply python scripts/reset_stuck_task.py --all --apply ```
External agent is not available Run: ```bash opc status ``` Check `.opc/config/agent_config.yaml` for command names such as `codex`, `claude`, `cursor-agent`, `opencode`, and `jiuwenswarm`. Gateway mode also requires a running `jiuwenswarm-start` service; use `opc agents preflight jiuwen` to verify it.
Channel provider receives no messages Check: - The provider extra is installed, for example `pip install -e .[channels-feishu]`. - The provider is `enabled: true`. - Required credentials are filled. - `allow_from` contains the sender IDs you expect. - `opc channels status` reports the provider as configured and available.
## Ecosystem And Sharing Everything OpenOPC builds is yours to keep, reuse, and share — organizations, employees, talent templates, skills, and channels are just files. Import a popular talent library, reuse a team across projects, or package a whole company as a shareable `.opcpkg`. ```bash # Hire from a talent library (e.g. agency-agents) into a role opc talent import /path/to/agency-agents opc talent hire -p demo # Reuse or share a whole organization opc org export --json > my-org.yaml opc market export --id hku_lab --name "HKU Lab" --output-dir packages opc market install packages/hku_lab.opcpkg ``` ## Roadmap OpenOPC is moving quickly. The areas below reflect active development priorities — each grounded in real gaps identified during early usage. | Area | Planned direction | |---|---| | **Role-level skills** | Role config already carries `skill_refs`, and the Org UI surfaces skill metadata today. The next step is letting users select which skills mount to which roles directly from the Org page — feeding into a broader self-evolving skill ecosystem. | | **Secretary settings** | The secretary will grow into a stronger configuration and memory steward: owning OPC system memory, analysing and comparing projects, and providing guided setup for OpenOPC YAML configuration. | | **Company-mode channels** | External channels will evolve beyond simple chat entrypoints into richer company-mode workflows — with role-aware notifications, structured approvals, and cross-platform collaboration. | | **CLI parity** | The CLI is functional today, but the Office UI remains the more complete surface. Upcoming work targets org editing, company-mode inspection, failure recovery, and long-running runtime control from the terminal. | | **TUI** | A full terminal UI is under consideration once CLI parity matures. The Office UI remains the primary interface in the meantime. | | **Market and presets** | More architecture presets, recruitable talent packs, import/export workflows, and a package marketplace for sharing and discovering community-built components. | | **Runtime polish** | Continued improvements to recovery, checkpointing, execution-progress visibility, and visual documentation — making long company runs more observable and resilient. | ## Acknowledgements OpenOPC is built with gratitude for several open-source projects that helped shape its agent design, skill structure, and talent template ecosystem: - [openai/codex](https://github.com/openai/codex/) for inspiring practical coding-agent workflows and execution patterns. - [BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) for inspiration around kanban-centered agent work management and task visibility. - [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) for the talent-template foundation. All talent templates included in this repository are imported from `agency-agents`. - [HKUDS/nanobot](https://github.com/HKUDS/nanobot) for inspiration around skill-oriented agent design and `SKILL.md`-style organization. - [pixel-agents-hq/pixel-agents](https://github.com/pixel-agents-hq/pixel-agents) for inspiration around the animated pixel-art office visualization of agent activity. ---

❤️ Thanks for visiting ✨ OpenOPC!

Views