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.
openclaw plugins install @honcho-ai/openclaw-honcho
Then enable it:
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:
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:
openclaw honcho setup
This command will:
- Prompt interactively for your Honcho API key
- Write configuration to
~/.openclaw/openclaw.json
- 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
openclaw gateway restart
Step 4: Confirm
Verify the plugin is active by checking gateway logs or running:
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_context, honcho_search_conclusions, honcho_ask, honcho_search_messages, honcho_session, 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
1---2name: honcho-setup3description: >4 Install the @honcho-ai/openclaw-honcho plugin and run initial setup.5 Runs `openclaw plugins install`, `openclaw honcho setup` (which prompts6 for your API key and migrates any legacy memory files to Honcho), and7 restarts the gateway. **UPLOADS WORKSPACE CONTENT TO EXTERNAL API** via8 `openclaw honcho setup`: sends USER.md, MEMORY.md, IDENTITY.md, memory/,9 canvas/, SOUL.md, AGENTS.md, BOOTSTRAP.md, TOOLS.md to api.honcho.dev10 (managed, default) or your self-hosted HONCHO_BASE_URL. HEARTBEAT.md is excluded. Requires explicit interactive user confirmation before uploading,11 even when HONCHO_API_KEY is pre-set. No workspace or memory files are12 deleted, moved, or modified. `openclaw honcho setup` writes plugin13 configuration to ~/.openclaw/openclaw.json. After setup, the plugin14 persistently observes conversations and transmits data to Honcho across15 sessions; disable with `openclaw plugins disable openclaw-honcho`.16metadata:17 openclaw:18 emoji: "🧠"19 required_env: [] # Nothing is strictly required - self-hosted mode works without API key20 optional_env:21 - name: HONCHO_API_KEY22 description: "Required for managed Honcho (https://app.honcho.dev). If set, the setup command skips the API key prompt but still requires explicit user confirmation before any data upload. If not set, the setup command will prompt for it interactively."23 - name: HONCHO_BASE_URL24 description: "Base URL for a self-hosted Honcho instance (e.g. http://localhost:8000). Defaults to https://api.honcho.dev (managed)."25 required_binaries:26 - node27 - npm28 writes_to_disk: true # openclaw honcho setup writes config to ~/.openclaw/openclaw.json29 reads_sensitive_files:30 - "~/.openclaw/openclaw.json - read and updated by openclaw honcho setup; API key collected via interactive prompt and written here"31 network_access:32 - "api.honcho.dev (managed mode, default)"33 - "User-configured HONCHO_BASE_URL (self-hosted mode)"34 data_handling:35 uploads_to_external: true36 requires_user_confirmation: true37 deletes_files: false38 modifies_files: false39 external_destinations:40 - "api.honcho.dev (managed Honcho, default)"41 - "User-configured HONCHO_BASE_URL (self-hosted mode)"42 uploaded_content:43 - "USER.md, MEMORY.md (user profile/memory files)"44 - "All files under memory/ directory (structured memory)"45 - "All files under canvas/ directory (working memory)"46 - "SOUL.md, IDENTITY.md, AGENTS.md, BOOTSTRAP.md, TOOLS.md (agent configuration)"47 - "HEARTBEAT.md excluded — it is a live task queue, not memory"48 data_destination_purpose: "Migrates file-based memory system to Honcho API for AI agent memory/personalization"49 homepage: "https://honcho.dev"50 source: https://skillmd.com/skills/plastic-labs/honcho-setup51 upstream: "https://github.com/plastic-labs/honcho"52---5354# Honcho Setup5556Install 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.5758> ⚠️ **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.5960> **No local files are deleted, moved, or modified.** Originals remain exactly in place.6162## Step 1: Install the Plugin6364Install 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.**6566```bash67openclaw plugins install @honcho-ai/openclaw-honcho68```6970Then enable it:7172```bash73openclaw plugins enable openclaw-honcho74```7576Verify the plugin loaded without errors. If the gateway logs show `Cannot find module '@honcho-ai/sdk'`, install dependencies manually:7778```bash79cd ~/.openclaw/extensions/openclaw-honcho && npm install80```8182This is a known issue with the OpenClaw plugin installer not running dependency resolution for plugin packages.8384## Step 2: Run Setup8586Run the setup command that ships with the plugin:8788```bash89openclaw honcho setup90```9192This command will:931. Prompt interactively for your Honcho API key942. Write configuration to `~/.openclaw/openclaw.json`953. Scan for legacy memory files and offer to migrate them to Honcho9697Follow the prompts. Migration is optional — if you have no legacy files or want to skip, you can skip the upload step.9899For 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.100101## Step 3: Restart the Gateway102103```bash104openclaw gateway restart105```106107## Step 4: Confirm108109Verify the plugin is active by checking gateway logs or running:110111```bash112openclaw honcho status113```114115Honcho memory is now active.116117> **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_context`, `honcho_search_conclusions`, `honcho_ask`, `honcho_search_messages`, `honcho_session`, and related tools. To stop this behavior, disable the plugin with `openclaw plugins disable openclaw-honcho`.118119---120121## Security & Privacy Disclosure122123This skill has been designed with transparency and safety as priorities. Below is a complete disclosure of what this skill does:124125### What This Skill Does126This 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.127128### Data Upload129- **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 migration130- **not_uploaded**: HEARTBEAT.md — excluded by design, never read or uploaded131- **Where it goes**: By default to `api.honcho.dev` (managed Honcho cloud service). For self-hosted instances, to your configured `HONCHO_BASE_URL`132- **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 URL133- **Purpose**: Migrating file-based memory system to Honcho API for AI agent personalization and memory134135### File Modifications136- **Config written**: `openclaw honcho setup` writes API key and config to `~/.openclaw/openclaw.json`137- **Workspace files**: Never modified — originals remain exactly in place138- **HEARTBEAT.md**: Never read or uploaded — excluded by design139140### Credentials141- **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.142- **No other credentials**: This skill does not access, read, or transmit any other credentials or secrets143144### Network Access145- **Managed mode**: Connects to `api.honcho.dev` (Honcho cloud service)146- **Self-hosted mode**: Connects to your configured `HONCHO_BASE_URL` (e.g., `http://localhost:8000`)147148### Ongoing Behavior After Setup149- **Persistent observation**: Once enabled, the plugin observes all conversations in the workspace and transmits conversation data to the configured Honcho endpoint on an ongoing basis150- **Network activity**: Continues across sessions as long as the plugin is enabled — this is not a one-time migration151- **How to stop**: Run `openclaw plugins disable openclaw-honcho` to stop all observation and network activity152153### Open Source154- **Honcho SDK**: Open source at https://github.com/plastic-labs/honcho155- **Plugin code**: Available at `~/.openclaw/extensions/openclaw-honcho` after installation156- **This skill**: You are reading the complete skill instructions - there is no hidden behavior