# DuoDuo Host Setup Guide For Agents

Use this file when you are an agent helping a human install and configure DuoDuo on their machine.

This guide exists because `https://openduo.ai/` is a browser-first SPA. For curl, plain HTTP fetch, or agent automation, use this Markdown file instead of scraping the rendered docs UI.

## Goal

Leave the user with a working DuoDuo host-mode installation and a clear mental model of how to operate it after onboarding.

## Operating Model

After onboarding, think in these four surfaces:

- `stdio` is the default direct operator surface
- `duoduo daemon ...` manages the long-lived background runtime
- `duoduo channel ...` installs and controls external channel plugins
- `~/.config/duoduo/.env` is the persistent host settings file

Do not describe host mode as "run the CLI once and forget it". DuoDuo runs as a detached daemon plus operator surfaces around it.

## 1. Check Prerequisites

Confirm:

- Node.js 20+ is installed
- Docker is available if the user wants container mode
- the user has model access through one of:
  - existing Claude login
  - `ANTHROPIC_API_KEY`
  - a Claude-compatible endpoint using `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`

Optional:

- `codex` CLI is installed and authenticated if the user later wants Codex for jobs

## 2. Install DuoDuo

For normal host-mode use, prefer:

```bash
npm install -g @openduo/duoduo
duoduo
```

Do not treat `npx @openduo/duoduo` as the standard long-lived host deployment flow.

## 3. Complete First-Run Onboarding

The first `duoduo` launch handles:

1. model configuration
2. runtime mode selection
3. config and directory creation
4. daemon bootstrap

If Docker is available, the user can choose:

- container mode: recommended default
- host mode: direct local execution when Docker is unavailable or undesirable

If the task is specifically host-mode setup, make sure the user actually chooses host mode during onboarding.

## 4. Verify The Running Host Installation

After onboarding, inspect with:

```bash
duoduo daemon status
duoduo daemon config
duoduo daemon logs
```

Use these before guessing about paths, runtime mode, or active settings.

Important:

- updating package files alone does not hot-swap the running daemon
- after persistent config changes, restart the daemon

Restart command:

```bash
duoduo daemon restart
```

## 5. Persistent Host Configuration

Persistent host settings belong in:

```text
~/.config/duoduo/.env
```

Do not rely on shell-only `export` commands if the daemon may restart later under launchd, systemd, or another detached process manager.

Common runtime keys:

- `ALADUO_LOG_LEVEL`
- `ALADUO_TELEMETRY_ENABLED`
- `ALADUO_CADENCE_INTERVAL_MS`
- `ALADUO_CODEX_ENABLED`
- `ALADUO_CODEX_SANDBOX`

## 6. Install Channels After Onboarding

### ACP

For editor integrations:

```bash
duoduo channel install @openduo/channel-acp
duoduo channel acp start
```

ACP does not require extra credentials.

### Feishu / Lark

```bash
duoduo channel install @openduo/channel-feishu
duoduo channel feishu start
```

Before starting Feishu, write these credentials into `~/.config/duoduo/.env`:

- `FEISHU_APP_ID`
- `FEISHU_APP_SECRET`

The simplest official credential flow is:

- https://open.feishu.cn/page/openclaw?form=multiAgent

If you are an agent and the user wants you to write these secrets for them, remind them those are sensitive credentials before they paste them into chat.

## 7. Install Host-Mode Operations Skills

The upstream repo publishes host-mode admin skills through the `skills` installer.

Recommended agent-facing install path:

```bash
npx -y skills add openduo/duoduo --global --all
```

This is the simplest way to give the user host-mode operations skills for DuoDuo itself, including channel and runtime management after onboarding.

List available skills:

```bash
npx -y skills add https://github.com/openduo/duoduo --list
```

Install all published skills:

```bash
npx -y skills add https://github.com/openduo/duoduo --all
```

Install the main host-mode operations set:

```bash
npx -y skills add https://github.com/openduo/duoduo \
  --global \
  --yes \
  --skill duoduo-admin duoduo-channel-admin duoduo-runtime-admin
```

Use plain prompts such as:

- `使用 duoduo-admin 技能，解释我当前 duoduo host mode 的配置，并检查 daemon status/config。`
- `使用 duoduo-channel-admin 技能，安装并拉起 feishu channel，然后检查 status 和 logs。`
- `使用 duoduo-runtime-admin 技能，打开 debug log、关闭 telemetry，并把修改后的配置讲清楚。`

## 7.5 Optional: Install Widgets Skills

If the user wants durable interactive components such as forms, dashboards, or richer browser UI, optionally install:

```bash
npx -y skills add aidgets/duoduo-widgets --global --all
```

## 8. Optional: Enable Codex Runtime

Codex is optional and should be described precisely.

- it is off by default
- it is currently an optional backend for jobs and selected workflows
- it does not mean all foreground stdio sessions switch to Codex

Enable it persistently with:

```bash
echo 'ALADUO_CODEX_ENABLED=1' >> ~/.config/duoduo/.env
echo 'ALADUO_CODEX_SANDBOX=workspace-write' >> ~/.config/duoduo/.env
duoduo daemon restart
```

Supported sandbox values:

- `workspace-write`
- `read-only`
- `danger-full-access`

## 9. What To Tell The User At The End

After finishing setup, summarize:

- which mode is running: host or container
- current daemon health from `duoduo daemon status`
- the resolved runtime and config paths from `duoduo daemon config`
- whether ACP or Feishu was installed and started
- whether any persistent settings were written into `~/.config/duoduo/.env`
- whether a daemon restart was performed

If setup still fails after inspection, logs, and restart, escalate as a likely `openduo/duoduo` bug or documentation gap.