honcho-setup

安装 @honcho-ai/openclaw-honcho 插件并运行初始设置。 运行“openclaw plugins install”、“openclaw honcho setup”（会提示 获取您的 API 密钥并将所有旧内存文件迁移到 Honcho），以及 重新启动网关。 **通过以下方式将工作空间内容上传到外部 API** `openclaw honcho setup`：发送 USER.md、MEMORY.md、IDENTITY.md、memory/、 canvas/、SOUL.md、AGENTS.md、BOOTSTRAP.md、TOOLS.md 到 api.honcho.dev （托管，默认）或您自托管的 HONCHO_BASE_URL。 HEARTBEAT.md 是 排除。上传前需要明确的交互式用户确认， 即使 HONCHO_API_KEY 已预先设置。没有工作区或内存文件 删除、移动或修改。 `openclaw honcho setup` 编写插件 配置到~/.openclaw/openclaw.json。设置好后，插件 持续观察对话并将数据传输给 Honcho 会议；使用“openclaw 插件禁用 openclaw-honcho”禁用。

# Honcho Setup

Install the `@honcho-ai/openclaw-honcho` plugin. The plugin includes `openclaw honcho setup`, which handles API key configuration and migration of any legacy memory files to Honcho.

> ⚠️ **DATA UPLOAD WARNING**: `openclaw honcho setup` (run in Step 2) will offer to upload your workspace memory files (USER.md, MEMORY.md, IDENTITY.md, memory/, canvas/, SOUL.md, AGENTS.md, BOOTSTRAP.md, TOOLS.md) to an external API. `HEARTBEAT.md` is excluded. By default, data is sent to `api.honcho.dev`. For self-hosted instances, data is sent to your configured `HONCHO_BASE_URL`. The setup command will show exactly which files will be uploaded and ask for explicit confirmation before proceeding.

> **No local files are deleted, moved, or modified.** Originals remain exactly in place.

## Step 1: Install the Plugin

Install the Honcho plugin using the OpenClaw plugin system. **Use this exact command — do not install `@honcho-ai/sdk` directly or use `npm install` in the workspace.**

```bash
openclaw plugins install @honcho-ai/openclaw-honcho
```

Then enable it:

```bash
openclaw plugins enable openclaw-honcho
```

Verify the plugin loaded without errors. If the gateway logs show `Cannot find module '@honcho-ai/sdk'`, install dependencies manually:

```bash
cd ~/.openclaw/extensions/openclaw-honcho && npm install
```

This is a known issue with the OpenClaw plugin installer not running dependency resolution for plugin packages.

## Step 2: Run Setup

Run the setup command that ships with the plugin:

```bash
openclaw honcho setup
```

This command will:
1. Prompt interactively for your Honcho API key
2. Write configuration to `~/.openclaw/openclaw.json`
3. Scan for legacy memory files and offer to migrate them to Honcho

Follow the prompts. Migration is optional — if you have no legacy files or want to skip, you can skip the upload step.

For managed Honcho, you need an API key from https://app.honcho.dev. For self-hosted instances, set `HONCHO_BASE_URL` to your instance URL and the API key is optional.

## Step 3: Restart the Gateway

```bash
openclaw gateway restart
```

## Step 4: Confirm

Verify the plugin is active by checking gateway logs or running:

```bash
openclaw honcho status
```

Honcho memory is now active.

> **Ongoing behavior after setup**: Once enabled, the plugin will persistently observe conversations in this workspace and send conversation data to `api.honcho.dev` (or your configured `HONCHO_BASE_URL`) to build and retrieve memory. This is ongoing network activity that continues across sessions. Memory is made available via `honcho_recall`, `honcho_search`, `honcho_profile`, and related tools. To stop this behavior, disable the plugin with `openclaw plugins disable openclaw-honcho`.

---

## Security & Privacy Disclosure

This skill has been designed with transparency and safety as priorities. Below is a complete disclosure of what this skill does:

### What This Skill Does
This skill runs three commands: `openclaw plugins install`, `openclaw honcho setup`, and `openclaw gateway restart`. The data upload and file access described below is performed by `openclaw honcho setup`, not by this skill directly.

### Data Upload
- **uploaded_content**: USER.md, MEMORY.md, IDENTITY.md, all files under memory/, all files under canvas/, SOUL.md, AGENTS.md, BOOTSTRAP.md, TOOLS.md — uploaded by `openclaw honcho setup` during migration
- **not_uploaded**: HEARTBEAT.md — excluded by design, never read or uploaded
- **Where it goes**: By default to `api.honcho.dev` (managed Honcho cloud service). For self-hosted instances, to your configured `HONCHO_BASE_URL`
- **User control**: `openclaw honcho setup` always requires explicit interactive confirmation before any upload, even when `HONCHO_API_KEY` is pre-set in the environment. You will see the exact list of files and the destination URL
- **Purpose**: Migrating file-based memory system to Honcho API for AI agent personalization and memory

### File Modifications
- **Config written**: `openclaw honcho setup` writes API key and config to `~/.openclaw/openclaw.json`
- **Workspace files**: Never modified — originals remain exactly in place
- **HEARTBEAT.md**: Never read or uploaded — excluded by design

### Credentials
- **HONCHO_API_KEY**: Required only for managed Honcho (api.honcho.dev). Not required for self-hosted instances. Stored in `~/.openclaw/openclaw.json` by the setup command.
- **No other credentials**: This skill does not access, read, or transmit any other credentials or secrets

### Network Access
- **Managed mode**: Connects to `api.honcho.dev` (Honcho cloud service)
- **Self-hosted mode**: Connects to your configured `HONCHO_BASE_URL` (e.g., `http://localhost:8000`)

### Ongoing Behavior After Setup
- **Persistent observation**: Once enabled, the plugin observes all conversations in the workspace and transmits conversation data to the configured Honcho endpoint on an ongoing basis
- **Network activity**: Continues across sessions as long as the plugin is enabled — this is not a one-time migration
- **How to stop**: Run `openclaw plugins disable openclaw-honcho` to stop all observation and network activity

### Open Source
- **Honcho SDK**: Open source at https://github.com/plastic-labs/honcho
- **Plugin code**: Available at `~/.openclaw/extensions/openclaw-honcho` after installation
- **This skill**: You are reading the complete skill instructions - there is no hidden behavior

---

## 中文说明

# Honcho 设置

安装 `@honcho-ai/openclaw-honcho` 插件。该插件包含 `openclaw honcho setup`，负责处理 API 密钥配置以及将任何旧版内存文件迁移到 Honcho。

> ⚠️ **数据上传警告**：`openclaw honcho setup`（在步骤 2 中运行）会提议将你的工作区内存文件（USER.md、MEMORY.md、IDENTITY.md、memory/、canvas/、SOUL.md、AGENTS.md、BOOTSTRAP.md、TOOLS.md）上传到外部 API。`HEARTBEAT.md` 被排除。默认情况下，数据发送到 `api.honcho.dev`。对于自托管实例，数据发送到你配置的 `HONCHO_BASE_URL`。设置命令会准确显示将上传哪些文件，并在继续之前要求明确确认。

> **不会删除、移动或修改任何本地文件。** 原始文件保持原样、原位不变。

## 步骤 1：安装插件

使用 OpenClaw 插件系统安装 Honcho 插件。**请使用此确切命令——不要直接安装 `@honcho-ai/sdk`，也不要在工作区中使用 `npm install`。**

```bash
openclaw plugins install @honcho-ai/openclaw-honcho
```

然后启用它：

```bash
openclaw plugins enable openclaw-honcho
```

验证插件加载无误。如果网关日志显示 `Cannot find module '@honcho-ai/sdk'`，请手动安装依赖：

```bash
cd ~/.openclaw/extensions/openclaw-honcho && npm install
```

这是 OpenClaw 插件安装程序未对插件包运行依赖解析的一个已知问题。

## 步骤 2：运行设置

运行插件附带的设置命令：

```bash
openclaw honcho setup
```

此命令将：
1. 交互式提示你输入 Honcho API 密钥
2. 将配置写入 `~/.openclaw/openclaw.json`
3. 扫描旧版内存文件并提议将它们迁移到 Honcho

按照提示操作。迁移是可选的——如果你没有旧版文件或想跳过，可以跳过上传步骤。

对于托管版 Honcho，你需要从 https://app.honcho.dev 获取 API 密钥。对于自托管实例，将 `HONCHO_BASE_URL` 设置为你的实例 URL，API 密钥则为可选。

## 步骤 3：重启网关

```bash
openclaw gateway restart
```

## 步骤 4：确认

通过检查网关日志或运行以下命令验证插件已激活：

```bash
openclaw honcho status
```

Honcho 内存现已激活。

> **设置后的持续行为**：启用后，插件会持续观察此工作区中的对话，并将对话数据发送到 `api.honcho.dev`（或你配置的 `HONCHO_BASE_URL`）以构建和检索内存。这是跨会话持续进行的网络活动。内存通过 `honcho_recall`、`honcho_search`、`honcho_profile` 及相关工具提供。要停止此行为，请使用 `openclaw plugins disable openclaw-honcho` 禁用插件。

---

## 安全与隐私披露

本技能在设计时将透明性和安全性作为优先事项。以下是本技能行为的完整披露：

### 本技能的功能
本技能运行三个命令：`openclaw plugins install`、`openclaw honcho setup` 和 `openclaw gateway restart`。下文描述的数据上传和文件访问由 `openclaw honcho setup` 执行，而非本技能直接执行。

### 数据上传
- **uploaded_content**：USER.md、MEMORY.md、IDENTITY.md、memory/ 下的所有文件、canvas/ 下的所有文件、SOUL.md、AGENTS.md、BOOTSTRAP.md、TOOLS.md——在迁移期间由 `openclaw honcho setup` 上传
- **not_uploaded**：HEARTBEAT.md——按设计排除，从不读取或上传
- **去向**：默认发送到 `api.honcho.dev`（托管版 Honcho 云服务）。对于自托管实例，发送到你配置的 `HONCHO_BASE_URL`
- **用户控制**：`openclaw honcho setup` 在任何上传之前始终要求明确的交互式确认，即使环境中已预设 `HONCHO_API_KEY`。你将看到文件的确切列表和目标 URL
- **目的**：将基于文件的内存系统迁移到 Honcho API，用于 AI 智能体的个性化和内存

### 文件修改
- **写入配置**：`openclaw honcho setup` 将 API 密钥和配置写入 `~/.openclaw/openclaw.json`
- **工作区文件**：从不修改——原始文件保持原样、原位不变
- **HEARTBEAT.md**：从不读取或上传——按设计排除

### 凭证
- **HONCHO_API_KEY**：仅托管版 Honcho（api.honcho.dev）需要。自托管实例不需要。由设置命令存储在 `~/.openclaw/openclaw.json` 中。
- **无其他凭证**：本技能不访问、读取或传输任何其他凭证或密钥

### 网络访问
- **托管模式**：连接到 `api.honcho.dev`（Honcho 云服务）
- **自托管模式**：连接