### Start OpenClacky Server (WebUI Mode)

Source: https://www.openclacky.com/docs/installation

Run this command after installation to start the OpenClacky local server. Access the Web UI by navigating to http://127.0.0.1:7070 in your browser. This is the recommended mode for beginners.

```bash
openclacky server
```

--------------------------------

### Install Additional Skill

Source: https://www.openclacky.com/docs/built-in-skills

Demonstrates installing an additional skill from a URL. Installed skills are managed in the `~/.clacky/skills/` directory.

```bash
/skill-add https://your-skill-url.zip

```

--------------------------------

### Minimal Slack Adapter Implementation

Source: https://www.openclacky.com/docs/extend-channel-adapter

A basic example of a Slack adapter extending Clacky's base adapter. It includes methods for platform identification, configuration, starting and stopping the adapter, sending messages, and validating configuration.

```ruby
require "clacky"

module ClackyChannels
  class SlackAdapter < Clacky::Channel::Adapters::Base
    def self.platform_id
      :slack
    end

    def self.platform_config(raw)
      {
        bot_token: raw[:bot_token],
        signing_secret: raw[:signing_secret]
      }
    end

    def initialize(config)
      @config = config
      @running = false
    end

    def start(&on_message)
      @running = true
      while @running
        # replace with a real long-poll / socket loop
        sleep 1
      end
    end

    def stop
      @running = false
    end

    def send_text(chat_id, text, reply_to: nil)
      # call Slack API; demo only
      { message_id: "demo-#{Time.now.to_i}" }
    end

    def validate_config(config)
      errors = []
      errors << "bot_token is required" if config[:bot_token].to_s.empty?
      errors
    end
  end
end

Clacky::Channel::Adapters.register(:slack, ClackyChannels::SlackAdapter)

```

--------------------------------

### Install OpenClacky Client

Source: https://www.openclacky.com/docs/publish-your-first-skill-in-5-min

Use this command to install the OpenClacky client locally. Ensure you replace 'your-brand-name' and 'package-name' with your specific details.

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)" -- --brand-name=your-brand-name --command=package-name

```

--------------------------------

### Example Project Rules File

Source: https://www.openclacky.com/docs/clackyrules

This example demonstrates how to structure a project rules file, including tech stack, commands, and conventions. Use headers for better agent scanning.

```markdown
# My Project

## Tech Stack
- Ruby on Rails 7.2 + PostgreSQL
- Stimulus + Hotwire Turbo (no jQuery, no inline JS)
- Tailwind CSS with custom design tokens

## Commands
- `bin/dev` — start dev server (never use `rails s`)
- `rake test` — run full test suite
- `rails runner 'code'` — run one-off Ruby

## Conventions
- All Stimulus controllers must be TypeScript
- Never use raw Tailwind color classes — use semantic tokens
- Controllers render turbo_stream templates, no respond_to blocks

```

--------------------------------

### Start Web Server with Custom Host and Port

Source: https://www.openclacky.com/docs/web-server

Starts the web server with a custom host and port. Useful for accessibility or avoiding port conflicts.

```bash
# Custom host/port
openclacky server --host 0.0.0.0 --port 8080

```

--------------------------------

### Install Skill from URL or Local Zip

Source: https://www.openclacky.com/docs/built-in-skills

Use this command to install a new skill from a provided URL or a local zip file. The skill will be automatically downloaded, extracted, and placed in the `~/.clacky/skills/` directory.

```bash
/skill-add https://store.example.com/my-skill-1.0.zip
/skill-add ~/Downloads/my-skill.zip

```

--------------------------------

### OpenAI Provider Configuration

Source: https://www.openclacky.com/docs/agent-config

Example configuration for using an OpenAI model. This setup is compatible with OpenAI's API structure.

```yaml
models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

```

--------------------------------

### Browser configuration file example

Source: https://www.openclacky.com/docs/browser-tool

An example of the `~/.clacky/browser.yml` configuration file. The `user_data_dir` can be optionally specified to manually set the user data directory.

```yaml
# ~/.clacky/browser.yml
user_data_dir: /path/to/UserDataDir   # optional: manually specify user data directory

```

--------------------------------

### Start OpenClacky Server on Custom Host and Port

Source: https://www.openclacky.com/docs/cli-reference

Starts the OpenClacky Web UI server, exposing it on all network interfaces and a custom port.

```bash
openclacky server --host 0.0.0.0 --port 8080

```

--------------------------------

### Full Example

Source: https://www.openclacky.com/docs/skill-frontmatter

A comprehensive skill definition including fork_agent, auto_summarize, and forbidden_tools.

```yaml
---
name: pdf-reader
description: >
  Read and analyze PDF files. Trigger on: "read this PDF", "what does this PDF say",
  "summarize the document", "帮我看这个PDF".
  Do NOT trigger for non-PDF file types.
fork_agent: true
auto_summarize: true
forbidden_tools:
  - write
  - edit
  - safe_shell
user-invocable: true
---

# PDF Reader

Extract and analyze content from PDF files...

```

--------------------------------

### GET /api/ext/my-dashboard/summary

Source: https://www.openclacky.com/docs/extend-api

Retrieves a summary of active sessions and the server start time.

```APIDOC
## GET /api/ext/my-dashboard/summary

### Description
Retrieves a summary of active sessions and the server start time.

### Method
GET

### Endpoint
/api/ext/my-dashboard/summary

### Response
#### Success Response (200)
- **sessions** (integer) - The number of active sessions.
- **started_at** (string) - The timestamp when the server started.

### Response Example
{
  "sessions": 5,
  "started_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Full Agent Configuration Example

Source: https://www.openclacky.com/docs/agent-config

This snippet shows a complete configuration file including both settings and multiple model definitions.

```yaml
settings:
  enable_compression: true
  enable_prompt_caching: true
  compression_threshold: 150000
  message_count_threshold: 200
  memory_update_enabled: true
  skill_evolution:
    enabled: true
    auto_create_threshold: 12
    reflection_mode: llm_analysis
  max_running_agents: 10
  max_idle_agents: 10
  default_working_dir:

models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

  - type: lite
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o-mini
    anthropic_format: false

```

--------------------------------

### Setup Channel Connection

Source: https://www.openclacky.com/docs/core-features

Run the setup command to connect OpenClacky to IM platforms like Feishu, WeCom, or WeChat. Each IM conversation is linked to an independent Session.

```cli
/channel-setup

```

--------------------------------

### Install OpenClacky via PowerShell Script (Windows)

Source: https://www.openclacky.com/docs/installation

Execute this PowerShell command to install OpenClacky on Windows systems. It downloads and runs the installation script from GitHub.

```powershell
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.ps1')))"
```

--------------------------------

### Start Agent Session with Specific Path and Mode

Source: https://www.openclacky.com/docs/cli-reference

Starts an agent session in a specified directory with the 'auto_approve' permission mode.

```bash
openclacky --path /path/to/project --mode auto_approve

```

--------------------------------

### Memory File Structure Example

Source: https://www.openclacky.com/docs/memory-system

Illustrates the directory structure and typical files within the OpenClacky memory system.

```shell
~/.clacky/memories/
  openclacky-product.md    # product decisions, architecture
  my-project.md            # project-specific context
  user-preferences.md      # how you like things done

```

--------------------------------

### Example User Prompts

Source: https://www.openclacky.com/docs/quickstart-guide

These are examples of natural language prompts you can use to interact with OpenClacky for various tasks.

```plaintext
Write a weekly work summary for me. This week I completed...
```

```plaintext
Organize the scattered files on my desktop into folders by type
```

```plaintext
Draft an email to my colleague explaining that the project is delayed
```

--------------------------------

### Scheduled Task Examples

Source: https://www.openclacky.com/docs/quickstart-guide

Examples of how to instruct OpenClacky to perform tasks on a recurring schedule.

```plaintext
Organize my to-do list every morning at 9 AM
```

```plaintext
Generate a weekly work summary every Friday at 5 PM
```

--------------------------------

### Start New Agent Session

Source: https://www.openclacky.com/docs/cli-reference

Starts a new interactive agent session in the current directory.

```bash
clacky

```

--------------------------------

### Troubleshooting Prompt Examples

Source: https://www.openclacky.com/docs/quickstart-guide

Examples contrasting ineffective and effective ways to phrase requests when the AI's response quality is not optimal.

```plaintext
❌ "Generate a structured analytical report based on Q3 business data"
```

```plaintext
✅ "Analyze last quarter's sales data for me — which products sold the best?"
```

--------------------------------

### OpenClacky Skills Examples

Source: https://www.openclacky.com/docs/channel-setup

Examples of how to invoke built-in Skills in OpenClacky for various tasks like SEO audits, Git commit messages, and translation.

```bash
/seo-audit https://example.com   # SEO diagnosis
/commit                           # Auto-generate Git commit messages
/translate                        # Professional translation

```

--------------------------------

### Start OpenClacky Server on Default Address

Source: https://www.openclacky.com/docs/cli-reference

Starts the OpenClacky Web UI server, listening on the default host (127.0.0.1) and port (7070).

```bash
openclacky server

```

--------------------------------

### Install OpenClacky via Bash Script (macOS/Linux)

Source: https://www.openclacky.com/docs/installation

Use this command to install OpenClacky and its dependencies on macOS and Linux systems via the terminal. It automatically handles Ruby and OpenClacky installation.

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
```

--------------------------------

### Structure for SKILL.md

Source: https://www.openclacky.com/docs/skill-creation-practices

Organize your SKILL.md file with a layered structure, starting from the overall goal and progressing to detailed edge case handling and examples.

```markdown
1. Overall goal (1-2 sentences)
2. Step-by-step workflow
3. Output format specification
4. Edge case handling
5. Examples (optional but effective)

```

--------------------------------

### Start a New CLI Session

Source: https://www.openclacky.com/docs/session-management

Run the `openclacky` command to start a fresh session in the current directory. You can also specify a project path.

```bash
openclacky
openclacky --path /path/to/project
```

--------------------------------

### Minimal Example

Source: https://www.openclacky.com/docs/skill-frontmatter

A basic skill definition with name, description, and instructions.

```yaml
---
name: code-reviewer
description: Review code for bugs and style issues. Trigger on "review my code", "check this file".
---

# Code Reviewer

Review the provided code and return a structured list of issues...

```

--------------------------------

### MCP Server Configuration Example

Source: https://www.openclacky.com/docs/mcp

This JSON configuration defines two MCP servers: one for filesystem access and another for GitHub integration. It shows how to specify commands, arguments, environment variables, and descriptions for each server. Place this in `~/.clacky/mcp.json` for global configuration.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
      "description": "Read/write files inside the projects folder."
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" },
      "description": "Search repos, read issues, open PRs."
    }
  }
}
```

--------------------------------

### Memory File YAML Header Example

Source: https://www.openclacky.com/docs/memory-system

Shows the YAML header format for memory files, including topic, description, and update timestamp.

```yaml
---
topic: my-project
description: Rails app architecture, conventions, key decisions
updated_at: 2026-03-17
---

# My Project

## Architecture
...

```

--------------------------------

### Get OpenClacky Version

Source: https://www.openclacky.com/docs/troubleshooting

Run this command in your terminal to retrieve the installed OpenClacky version, which is required for bug reports.

```bash
clacky --version
```

--------------------------------

### Initialize Skill Creator

Source: https://www.openclacky.com/docs/publish-your-first-skill-in-5-min

Run this command within your activated claw client to start the interactive process of creating a new skill.

```bash
/skill-creator

```

--------------------------------

### Run SEO Audit Skill

Source: https://www.openclacky.com/docs/advantages

This example demonstrates how to trigger the 'seo-audit' skill with a given URL. The skill provides an overall score and detailed recommendations.

```bash
/seo-audit https://myblog.com
→ Overall score + per-category diagnosis + prioritized recommendations
```

--------------------------------

### Skill Body Workflow Example

Source: https://www.openclacky.com/docs/writing-tips

Demonstrates structuring the Skill body to describe a workflow with imperative steps, rather than a persona. This helps the AI execute tasks reliably.

```markdown
# Code Reviewer

## Steps

1. Read the code or file path provided by the user
2. Check each of the following:
   - Obvious bugs or missing edge cases
   - Clear naming and readable logic
   - Performance risks (N+1 queries, unnecessary loops, etc.)
3. Output findings by severity: 🔴 Must Fix / 🟡 Suggested / 🟢 Optional
4. Include a fix suggestion and example code for each issue

```

--------------------------------

### Example ext.yml Manifest Structure

Source: https://www.openclacky.com/docs/ext-manifest

Illustrates the basic structure of an ext.yml manifest file, showing top-level fields like id, name, description, version, author, origin, and contributions.

```yaml
id: weather-panel          # unique container id (defaults to directory name); lowercase letters, digits, -, _
name: Weather Panel        # display name
description: Sidebar weather panel
version: "0.1.0"           # semantic version; used as-is on publish
author: Your Name          # credit, shown on the New Session card
origin: self               # source nature: self / marketplace / enterprise
contributes:               # contributions (see below)
  ...
```

--------------------------------

### Initiate Custom Skill Creation

Source: https://www.openclacky.com/docs/core-features

Use this command to start the interactive process of defining, writing, and testing a new custom skill.

```bash
/skill-creator
```

--------------------------------

### Referencing External Style Guides

Source: https://www.openclacky.com/docs/writing-tips

Shows how to reference external documentation, like style guides, from the SKILL.md body. This keeps the main Skill file concise.

```markdown
## Review Standards

See `references/code-style-guide.md` for detailed rules — read this file before starting the review.

```

--------------------------------

### Check chrome-devtools-mcp Version

Source: https://www.openclacky.com/docs/browser-troubleshooting

Verify the installation and version of the chrome-devtools-mcp executable. This command helps confirm that the daemon is correctly installed and available in the PATH.

```bash
chrome-devtools-mcp --version
```

--------------------------------

### Two Models Configuration (Default + Lite)

Source: https://www.openclacky.com/docs/agent-config

Configure both a default and a lite model for cost optimization. This setup is useful for main agent tasks and lightweight subtasks.

```yaml
models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

  - type: lite
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o-mini
    anthropic_format: false

```

--------------------------------

### Skill Steps for File Analysis and Reporting

Source: https://www.openclacky.com/docs/writing-tips

Provides an example of Skill steps that involve using tools to interact with files, perform analysis, and generate a report. This emphasizes making Skills perform actual tasks.

```markdown
## Steps

1. Use the glob tool to find all `*.rb` files in the project
2. Use file_reader to read each file and check for `TODO` comments
3. Summarize the results and write them to `todo_report.md`
4. Tell the user the report is ready at `./todo_report.md`

```

--------------------------------

### Manage Extension Lifecycle with `clacky ext`

Source: https://www.openclacky.com/docs/extension-system

Use these commands to scaffold, verify, list, pack, and install extensions. Changes to files like `view.js` or `handler.rb` take effect on the next request, while `ext.yml` edits require a reload.

```bash
# 1. Create a runnable skeleton (hello panel + backend) in ~/.clacky/ext/local/<id>/
clacky ext new weather-panel
clacky ext new weather-panel --full   # kitchen-sink sample using all seven contributions

# 2. Verify: resolve all containers, list contributed units + structured errors
clacky ext verify

# 3. List all resolved containers and what they contribute, who overrides whom
clacky ext list

# 4. Pack into a distributable zip
clacky ext pack weather-panel

# 5. Install someone else's extension (local zip path or http(s) URL) → installed layer
clacky ext install ./weather-panel.zip
clacky ext install https://example.com/weather-panel.zip

# 6. Search the public marketplace
clacky ext search weather

```

--------------------------------

### Example: SEO Audit Skill Usage

Source: https://www.openclacky.com/docs/how-to-use-a-skill

Demonstrates invoking the SEO Audit Skill with a URL. The AI will then perform an analysis and provide a detailed report.

```bash
# Click /, type "seo" to filter
/seo-audit https://example.com

# AI runs the expert-designed analysis and outputs:
# - Overall score and per-dimension scores
# - Issue list (sorted by severity)
# - Specific optimization recommendations
```

--------------------------------

### DeepSeek Provider Configuration

Source: https://www.openclacky.com/docs/agent-config

Example configuration for using the DeepSeek provider. Note the specific model name and base URL.

```yaml
models:
  - type: default
    api_key: sk-...
    base_url: https://api.deepseek.com/v1
    model: deepseek-chat
    anthropic_format: false

```

--------------------------------

### GET /models

Source: https://www.openclacky.com/docs/api-reference

Lists available models, compatible with OpenAI Models API.

```APIDOC
## GET /models

### Description
This endpoint lists all the models available for use with the OpenClacky API. It is compatible with the OpenAI Models API.

### Method
GET

### Endpoint
/models

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```
curl https://api.openclacky.com/models
```

### Response
#### Success Response (200)
- **object** (string) - The type of object, usually `list`.
- **data** (array) - A list of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of object, usually `model`.
  - **created** (integer) - Unix timestamp of when the model was created.
  - **owned_by** (string) - The organization that owns the model.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "created": 1649370119,
      "owned_by": "openai"
    },
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1686936000,
      "owned_by": "openai"
    }
  ]
}
```

ERROR HANDLING:
- **401 Unauthorized**: Invalid API key.
- **500 Internal Server Error**: Server error.
```

--------------------------------

### File Attachment Prompts

Source: https://www.openclacky.com/docs/quickstart-guide

Examples of prompts to use when attaching files to OpenClacky for analysis or summarization.

```plaintext
Summarize the key points of this PDF for me
```

```plaintext
Analyze the data in this spreadsheet and identify any trends
```

--------------------------------

### Invoke Skills with Slash Commands

Source: https://www.openclacky.com/docs/how-to-use-a-skill

Use slash commands to quickly invoke installed Skills. Type '/' and then the Skill name followed by any necessary arguments.

```bash
/seo-audit https://example.com
/contract-review
/commit
```

--------------------------------

### Multi-Project Workspace Rules File

Source: https://www.openclacky.com/docs/clackyrules

Example of a project rules file for a workspace containing multiple sub-projects. It outlines shared conventions and specific commands for each project.

```markdown
# My Workspace

Two sub-projects, developed in parallel.

## Project A: api/ — Rails backend
- PostgreSQL, Ruby 3.2
- `cd api && bin/dev` to start

## Project B: web/ — Next.js frontend  
- TypeScript, Tailwind
- `cd web && npm run dev` to start

## Shared conventions
- API versioned at /api/v1
- All dates in ISO 8601

```

--------------------------------

### GET /balance

Source: https://www.openclacky.com/docs/api-reference

Checks the current credit balance and quota.

```APIDOC
## GET /balance

### Description
This endpoint allows you to check your current credit balance and usage quota on OpenClacky.

### Method
GET

### Endpoint
/balance

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```
curl https://api.openclacky.com/balance
```

### Response
#### Success Response (200)
- **credit_balance** (number) - Your remaining credit balance.
- **quota_usage** (object) - Information about your current quota usage.
  - **limit** (integer) - The total limit for a given quota.
  - **used** (integer) - The amount of quota used.

#### Response Example
```json
{
  "credit_balance": 150.75,
  "quota_usage": {
    "limit": 100000,
    "used": 25000
  }
}
```

ERROR HANDLING:
- **401 Unauthorized**: Invalid API key.
- **500 Internal Server Error**: Server error.
```

--------------------------------

### Example Patch File Structure

Source: https://www.openclacky.com/docs/extend-patches

This snippet shows the basic structure of a patch file in Ruby. It demonstrates how to prepend a module to an existing class and override a method, calling the original implementation using 'super'.

```ruby
# ~/.clacky/ext/local/fix-search/patches/timeout.rb

module FixSearch
  def execute(query:)
    @timeout = 30      # e.g. bump timeout to 30s
    super              # then call the original
  end
end

Clacky::Tools::WebSearch.prepend(FixSearch)

```

--------------------------------

### Start OpenClacky CLI Mode

Source: https://www.openclacky.com/docs/installation

Use this command to interact with OpenClacky directly from your terminal. This mode is suitable for command-line chat interactions.

```bash
openclacky
```

--------------------------------

### Verify chrome-devtools-mcp Installation

Source: https://www.openclacky.com/docs/browser-troubleshooting

Check if the chrome-devtools-mcp executable is installed and accessible in your system's PATH. This command helps diagnose issues where browser-manager cannot find the necessary daemon.

```bash
which chrome-devtools-mcp
```

--------------------------------

### Call API Extension Endpoint

Source: https://www.openclacky.com/docs/extend-api

Examples of how to call your API extension endpoints. Loopback calls are auto-allowed, while remote calls require an access key.

```bash
# loopback is auto-allowed
curl http://127.0.0.1:7070/api/ext/my-dashboard/summary

# remote calls need the access key
curl -H "X-Clacky-Key: $(cat ~/.clacky/access_key)" \
     http://your-host:7070/api/ext/my-dashboard/summary

```

--------------------------------

### SKILL.md Description Field Examples

Source: https://www.openclacky.com/docs/skill-basics

Shows how to write effective 'description' fields in the SKILL.md frontmatter. A good description clearly states the Skill's purpose and lists specific trigger scenarios and keywords.

```yaml
# ❌ Too vague — will miss triggers
description: 'Helps with writing'

# ✅ Specific and accurate
description: 'Helps write and polish professional emails and business documents.
  Use when user wants to draft an email, revise a report, improve tone,
  or needs help with any writing task — even if they just say "help me write".'

```

--------------------------------

### Create a Scheduled Task

Source: https://www.openclacky.com/docs/built-in-skills

Initiate the creation of a new scheduled task. This command guides you through defining a task that will run automatically at a specified time, with definitions stored in `~/.clacky/tasks/` and schedules in `~/.clacky/schedules.yml`.

```bash
/cron-task-creator
> Create a task that summarizes my GitHub notifications every morning at 8am

```

--------------------------------

### Check WSL Status

Source: https://www.openclacky.com/docs/faq-windows-installation

After updating or repairing WSL, use this command to verify that WSL is ready for use. This is a diagnostic step before relaunching the installer.

```powershell
wsl --status

```

--------------------------------

### OpenClacky Skill Commands

Source: https://www.openclacky.com/docs/cron-tasks

Examples of built-in Skills that can be triggered to perform specific tasks. These skills are designed for direct use without complex prompt engineering.

```bash
/seo-audit https://example.com   # SEO diagnosis
/commit                           # Auto-generate Git commit messages
/translate                        # Professional translation
```

--------------------------------

### Run browser-setup skill

Source: https://www.openclacky.com/docs/browser-tool

Use the `browser-setup` skill to automatically configure your browser connection. This skill detects your environment and verifies the connection, saving settings to `~/.clacky/browser.yml`.

```shell
/browser-setup

```

--------------------------------

### Anthropic (Claude) Provider Configuration

Source: https://www.openclacky.com/docs/agent-config

Example configuration for using the Anthropic Claude model. Ensure you have the correct API key and base URL.

```yaml
models:
  - type: default
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    model: claude-sonnet-4-5
    anthropic_format: true

```

--------------------------------

### API Response Helper Examples

Source: https://www.openclacky.com/docs/extend-api

These methods send a response and halt the handler. Use `json` for JSON responses, `text` for plain text, and `error!` for JSON errors with custom status codes and fields. Code after these helpers will not execute.

```ruby
json(foo: 1, bar: 2)              # 200 + {"foo":1,"bar":2}
json({ items: [] }, status: 201)  # custom status
text("pong")                      # 200 text/plain
error!("not found", status: 404)  # 404 + {"error":"not found"}
error!("invalid", status: 422, fields: ["text"])  # 422 + extra fields
```

--------------------------------

### Alternative browser-setup commands

Source: https://www.openclacky.com/docs/browser-tool

These phrases can also be used to invoke the `browser-setup` skill for browser configuration.

```shell
setup browser

```

```shell
help me configure the browser

```

--------------------------------

### Invoke Skills with Natural Language

Source: https://www.openclacky.com/docs/how-to-use-a-skill

Describe your task in natural language, and the AI will automatically match and invoke the appropriate Skill if one is installed.

```text
Analyze the SEO issues on this website: example.com
```

--------------------------------

### Enter CLI Terminal Mode

Source: https://www.openclacky.com/docs/core-features

Run this command to enter Openclacky's interactive chat mode directly from your terminal. No server setup is required.

```bash
openclacky

```

--------------------------------

### Define API Extension Routes

Source: https://www.openclacky.com/docs/extend-api

Inherit from `Clacky::ApiExtension` and use `get`, `post`, `put`, `patch`, `delete` to define API endpoints. Use `json` to return JSON responses and `error!` for error handling.

```ruby
class MyDashboardExt < Clacky::ApiExtension
  get "/summary" do
    json(sessions: session_manager.list.size, started_at: server_start_time)
  end

  get "/sessions/:id" do
    sess = session_manager.find(params[:id]) or error!("not found", status: 404)
    json(id: sess.id, name: sess.name)
  end

  post "/notes" do
    text = json_body["text"].to_s
    error!("text required", status: 422) if text.empty?
    File.write(data_path("notes.txt"), "#{text}\n", mode: "a")
    json(ok: true)
  end
end
```

--------------------------------

### Curl Image Generation Request

Source: https://www.openclacky.com/docs/api-reference

Generate images using a curl command. This example shows how to set the authorization header, content type, and provide model and prompt details. The output is piped to base64 decode and saved as a PNG.

```bash
curl https://api.openclacky.com/images/generations \
  -H "Authorization: Bearer sk-oc-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "or-gemini-3-1-flash-image",
    "prompt": "a futuristic Tokyo street at night",
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 -d > out.png

```

--------------------------------

### Curl Text-to-Speech Request

Source: https://www.openclacky.com/docs/api-reference

Generate speech from text using a curl command. This example demonstrates setting the authorization header, content type, and specifying the model, input text, and voice. The output is base64 decoded and saved as a WAV file.

```bash
curl https://api.openclacky.com/audio/speech \
  -H "Authorization: Bearer sk-oc-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "or-tts-gemini-2-5-flash",
    "input": "Welcome to OpenClacky.",
    "voice": "Kore"
  }' | jq -r '.data[0].b64_json' | base64 -d > out.wav

```

--------------------------------

### Publish a Local Extension

Source: https://www.openclacky.com/docs/extension-system

Use the 'clacky ext publish' command to upload your local extension to the marketplace. The first publish prompts for device authorization. Subsequent publishes can include a changelog and force an update.

```bash
clacky ext publish weather-panel
```

```bash
clacky ext publish weather-panel --force --changelog "Fixed the night icon"
```

--------------------------------

### Configure OpenClacky Client

Source: https://www.openclacky.com/docs/ai-key-models

Set OpenClacky as the provider and enter your AI key. No further configuration is required.

```yaml
# Select OpenClacky in your client
# No additional configuration needed
provider: openclacky
api_key: clacky-your-key-here

```

--------------------------------

### GET /api/ext/my-dashboard/sessions/:id

Source: https://www.openclacky.com/docs/extend-api

Retrieves details for a specific session by its ID.

```APIDOC
## GET /api/ext/my-dashboard/sessions/:id

### Description
Retrieves details for a specific session by its ID.

### Method
GET

### Endpoint
/api/ext/my-dashboard/sessions/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the session.
- **name** (string) - The name of the session.

#### Response Example
{
  "id": "session-123",
  "name": "User Session"
}

#### Error Response (404)
- **message** (string) - "not found"

```

--------------------------------

### Scaffold New Channel Adapter

Source: https://www.openclacky.com/docs/extend-channel-adapter

Use this command to scaffold a new channel adapter, with an option for a full reference container.

```bash
clacky ext new slack-channel --full

```

--------------------------------

### description Field

Source: https://www.openclacky.com/docs/skill-frontmatter

Provides a description for the LLM to decide when to invoke the skill. Include example trigger phrases.

```yaml
description: >
  Analyze PDF files. Trigger on: "read this PDF", "what does this PDF say",
  "summarize the document", "帮我看这个PDF".

```

--------------------------------

### Update OpenClacky via RubyGems

Source: https://www.openclacky.com/docs/faq

Use this command to update OpenClacky to the latest version. Ensure you have RubyGems installed.

```bash
gem update openclacky

```

--------------------------------

### Describe Browser Automation Task

Source: https://www.openclacky.com/docs/core-features

Describe the browser automation task after running `/browser-setup` once. This allows the Agent to control Chrome/Edge for web interactions.

```natural language
Open GitHub and save a screenshot to the desktop

```

--------------------------------

### Verify Extension Registration

Source: https://www.openclacky.com/docs/extend-shell-hooks

Run `clacky ext verify` to check for errors in hook registration and event names. This command exits non-zero on any detected issues, making it suitable for CI.

```bash
clacky ext verify

```

--------------------------------

### Create a New OpenCLACKY Extension

Source: https://www.openclacky.com/docs/extension-system

Use this command to quickly scaffold a new extension. After creation, edit the generated files, verify the extension, and refresh the Web UI.

```bash
clacky ext new <id>
```

--------------------------------

### Scaffold a New Extension

Source: https://www.openclacky.com/docs/extend-shell-hooks

Use the `clacky ext new` command to generate a new extension. The `--full` flag includes sample contribution files for all hook types.

```bash
clacky ext new audit-guard --full

```

--------------------------------

### GET /api/ext/gh-webhook/recent

Source: https://www.openclacky.com/docs/extend-api

This endpoint allows local reading of recent events logged by the extension. An access key is required, but it is automatically allowed on loopback connections.

```APIDOC
## GET /api/ext/gh-webhook/recent

### Description
Retrieves a log of recent events processed by the webhook.

### Method
GET

### Endpoint
/api/ext/gh-webhook/recent

### Parameters
None

### Response
#### Success Response (200)
- **body** (string) - The content of the events log file.

#### Response Example
```
2023-10-27T10:00:00Z push action=created
2023-10-27T10:05:00Z pull_request action=opened
```
```

--------------------------------

### Generate New Extension Scaffold

Source: https://www.openclacky.com/docs/extend-api

Use this command to create a new API extension scaffold. It generates a basic hello panel and an api/handler.rb file. You can remove the panels directory and entry if only the backend is needed.

```bash
clacky ext new my-dashboard
```

--------------------------------

### SKILL.md Frontmatter and Body Structure

Source: https://www.openclacky.com/docs/skill-basics

Illustrates the basic format of a SKILL.md file, which includes YAML frontmatter for metadata and a Markdown body for instructions. Ensure frontmatter fields are correctly formatted.

```yaml
---
name: my-skill
description: 'Solves X problem. Trigger when user mentions X, Y, or Z.'
disable-model-invocation: false
user-invocable: true
---

# My Skill

Instructions for the AI go here...

```

--------------------------------

### Declare Panels in ext.yml

Source: https://www.openclacky.com/docs/extend-webui

Define extension panels and their associated view scripts in the `ext.yml` manifest file. Specify which agents the panel should attach to.

```yaml
# ~/.clacky/ext/local/my-badge/ext.yml
id: my-badge
name: My Badge
version: "0.1.0"
contributes:
  panels:
    - id: badge
      view: panels/badge/view.js   # panel script (relative to container root)
      attach: ["*"]                # attach to all agents; or [coding, designer] to scope

```

--------------------------------

### Verify API Extension Loading

Source: https://www.openclacky.com/docs/extend-api

This command checks if your API extensions are loading correctly. It reports OK or ERR status for each extension, exiting non-zero on any error, which is useful for CI pipelines.

```bash
clacky ext verify
```

```text
[OK]   my-dashboard (api → /api/ext/my-dashboard/, local)
[OK]   gh-webhook (api → /api/ext/gh-webhook/, local)
[ERR]  broken-one (api.handler.missing) — handler file not found [api/handler.rb]

```

--------------------------------

### Get Account Balance and Quota

Source: https://www.openclacky.com/docs/api-reference

Fetches the account balance and quota usage for the API key. The quota field is only included if quota is enabled and an amount is set for the key.

```json
{
  "is_available": true,
  "balance_infos": [
    { "currency": "USD", "total_balance": "5.0" }
  ],
  "quota": {
    "enabled": true,
    "amount": 10.0,
    "used": 3.5,
    "remaining": 6.5,
    "reset_period": "monthly"
  }
}
```

--------------------------------

### Scaffold a New Patch Extension

Source: https://www.openclacky.com/docs/extend-patches

Use this CLI command to scaffold a new patch extension. The --full flag includes a sample audit patch file.

```bash
clacky ext new fix-search --full

```

--------------------------------

### Downgrade OpenClacky to a Specific Version

Source: https://www.openclacky.com/docs/faq

To downgrade OpenClacky, first uninstall the current version and then install the desired version. Replace '1.0.4' with your target version. This process does not affect memories or configurations.

```bash
gem uninstall openclacky -a
gem install openclacky -v '1.0.4'

```

--------------------------------

### Any OpenAI-Compatible Provider Configuration

Source: https://www.openclacky.com/docs/agent-config

General configuration for any provider that is compatible with the OpenAI API. Replace placeholders with your provider's details.

```yaml
models:
  - type: default
    api_key: your-key
    base_url: https://your-provider.com/v1
    model: your-model-name
    anthropic_format: false

```

--------------------------------

### Declare Channel Contribution in ext.yml

Source: https://www.openclacky.com/docs/extend-channel-adapter

Define the channel adapter's metadata and its entry point script in the `ext.yml` manifest file.

```yaml
# ~/.clacky/ext/local/slack-channel/ext.yml
id: slack-channel
name: Slack Channel
version: "0.1.0"
contributes:
  channels:
    - id: slack
      adapter: channels/slack.rb   # adapter script (relative to container root)

```

--------------------------------

### Uninstall OpenClacky using Script

Source: https://www.openclacky.com/docs/faq

Run this script in your terminal to uninstall OpenClacky. It removes program files and prompts to keep configuration files. This method is applicable for both script-based and desktop installer users.

```bash
/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/uninstall.sh)"

```

--------------------------------

### Clacky.ext.ui.mount

Source: https://www.openclacky.com/docs/extend-webui

Mounts a UI component to a specified slot in the Clacky interface. The `renderFn` is executed when the slot needs to be rendered, and it receives a context object with session information and a method to update tab badges. Optional `opts` can configure agent visibility, panel association, rendering order, and tab properties.

```APIDOC
## Clacky.ext.ui.mount

### Description
Mounts a UI component to a specified slot in the Clacky interface. The `renderFn` is executed when the slot needs to be rendered, and it receives a context object with session information and a method to update tab badges. Optional `opts` can configure agent visibility, panel association, rendering order, and tab properties.

### Signature
```
Clacky.ext.ui.mount(slot, renderFn, opts?)
```

### Parameters
#### `slot`
- Type: `string`
- Description: The target slot in the Clacky UI to mount the component to (e.g., "session.aside").

#### `renderFn`
- Type: `function(ctx)`
- Description: A function that is called whenever the slot needs to render. It receives a context object `ctx`.
  - `ctx.agentProfile` (string | null): The current session's agent name.
  - `ctx.sessionId` (string | null): The current session ID.
  - `ctx.setBadge(n)` (function): **Only on tab slots** (`session.aside`): Updates the tab's badge counter. Pass `null` or `0` to clear.

#### `opts` (Optional)
- Type: `object`
- Description: Optional configuration options for the mounted component.
  - `opts.agents` (Array<string>): Restricts the extension to these agent profiles. Omitted means visible to all agents.
  - `opts.panel` (string): Marks the component as belonging to an official panel.
  - `opts.order` (number): Default `100`. Determines the rendering order among components in the same slot. Lower numbers render first.
  - `opts.tab` (`{ id, label, badge? }`): **Required when mounting to a tab container slot (`session.aside`).**
    - `id` (string): Must be unique within the slot.
    - `label` (string): The text displayed for the tab.
    - `badge` (any?): The initial badge counter value.

### Return Value
- Type: `DOM node` | `string` | `null`
- Description: Returns the rendered DOM node, an HTML string, or `null` if nothing should be rendered.

### Example
```javascript
// A complete session.aside tab example
Clacky.ext.ui.mount("session.aside", (ctx) => {
  if (!ctx.sessionId) return null;
  const root = document.createElement("div");
  root.textContent = `Session ${ctx.sessionId}`;
  ctx.setBadge(3);    // show "3" badge on this tab
  return root;
}, {
  order: 50,
  tab: { id: "my-tab", label: "Mine", badge: null },
});
```
```

--------------------------------

### Edit Image Background using cURL

Source: https://www.openclacky.com/docs/api-reference

Example using cURL to edit an image's background. It encodes the input image to base64, sends it via POST request, and decodes the resulting base64 image.

```bash
# edit an existing PNG: turn its background to night
B64=$(base64 -i input.png)
curl https://api.openclacky.com/images/generations \
  -H "Authorization: Bearer sk-oc-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"or-gemini-3-1-flash-image\",
    \"prompt\": \"change the background to a starry night sky\",
    \"image\": \"$B64\" 
  }" | jq -r '.data[0].b64_json' | base64 -d > edited.png

```

--------------------------------

### System Prompt Layering

Source: https://www.openclacky.com/docs/clackyrules

Illustrates where the project rules file is injected into the system prompt. It's loaded as Layer 3, after core instructions and before personality.

```markdown
Layer 1: Agent role & responsibilities
Layer 2: Universal behavioral rules
Layer 3: ← Your .clackyrules goes here
Layer 4: Agent personality (SOUL.md)
Layer 5: User profile (USER.md)
Layer 6: Available skills

```

--------------------------------

### Verify an OpenCLACKY Extension

Source: https://www.openclacky.com/docs/extension-system

Run this command to verify the integrity and correctness of your extension files before deployment or refresh.

```bash
clacky ext verify
```

--------------------------------

### Define Extension Manifest (ext.yml)

Source: https://www.openclacky.com/docs/extension-system

Use this structure to define your extension's metadata and contributions. Ensure the `id`, `name`, `version`, and `contributes` fields are correctly set.

```yaml
id: weather-panel
name: Weather Panel
description: Shows the current city's weather in the sidebar
version: "0.1.0"
author: Your Name
origin: self
contributes:
  api: api/handler.rb          # one backend endpoint
  panels:
    - id: weather
      view: panels/weather/view.js
      attach: ["*"]            # attach to all agents

```

--------------------------------

### Encrypt a Skill Directory

Source: https://www.openclacky.com/docs/encryption-ip-protection

Use this command to encrypt your Skill's `SKILL.md` file. The original `SKILL.md` remains on your local machine and is not uploaded.

```bash
openclacky

# Encrypt a Skill directory
/encrypt ./my-skill

# Output:
# ✅ SKILL.md.enc generated successfully
# Your original SKILL.md stays local — never uploaded


```

--------------------------------

### Vague vs. Specific Skill Description

Source: https://www.openclacky.com/docs/writing-tips

Illustrates how to write a specific and accurate 'description' field to ensure the AI correctly invokes the Skill. Use specific trigger keywords and scenarios.

```markdown
# ❌ Too vague
description: 'Helps with code review'

# ✅ Specific, accurate triggers
description: 'Reviews code for bugs, style issues, and performance problems.
  Use whenever the user pastes code and asks for feedback, says "review this",
  "check my code", "what's wrong here", or wants a PR review — even if they
  just say "look at this function".'
```

--------------------------------

### Skill Directory Structure

Source: https://www.openclacky.com/docs/skill-basics

Defines the standard file and directory layout for a Clacky Skill. The SKILL.md file is mandatory, while scripts, references, and assets are optional.

```bash
~
├── ~/.clacky/skills/my-skill/
│   ├── SKILL.md              # Required: core instruction file
│   ├── scripts/              # Optional: scripts (Ruby preferred)
│   ├── references/           # Optional: reference docs (loaded on demand)
│   └── assets/               # Optional: templates, icons, static files

```

--------------------------------

### Describe Scheduled Task

Source: https://www.openclacky.com/docs/core-features

Describe the desired task and its schedule. Ensure the `openclacky server` is running for automatic execution.

```natural language
Create a task that fetches AI news every morning at 9 AM

```

--------------------------------

### Declare API Contribution in ext.yml

Source: https://www.openclacky.com/docs/extend-api

Declare your API backend by specifying the path to your handler file in `ext.yml`. This contribution is mounted at `/api/ext/<id>/`.

```yaml
# ~/.clacky/ext/local/my-dashboard/ext.yml
id: my-dashboard
name: My Dashboard
version: "0.1.0"
contributes:
  api: api/handler.rb        # single handler, mounted at /api/ext/my-dashboard/

```

--------------------------------

### List Resolved API Extension Containers

Source: https://www.openclacky.com/docs/extend-api

Prints all containers and their contributed units, which is helpful for confirming API mount points.

```bash
clacky ext list
```

--------------------------------

### Executing External Scripts

Source: https://www.openclacky.com/docs/writing-tips

Demonstrates how to call external scripts (e.g., Ruby) from the Skill body for complex data processing tasks, promoting modularity.

```markdown
## Data Processing

Run `ruby SKILL_DIR/scripts/parse_report.rb <input_file>` to process the input data.

```

--------------------------------

### MCP Server Summary in Skill List

Source: https://www.openclacky.com/docs/mcp

Each MCP server is represented as a concise one-line summary in the agent's Skill list. This representation costs approximately 50 tokens per server, irrespective of the number of tools it exposes.

```text
mcp:github — Search repos, read issues, open PRs on GitHub.
```

--------------------------------

### Veo Video Generation (Async Submit)

Source: https://www.openclacky.com/docs/api-reference

Submit a request for asynchronous video generation using Veo models. This is the initial step for video creation.

```APIDOC
## POST /vertex/v1beta1/models/{model}:predictLongRunning

### Description
Submit a request for asynchronous video generation using Veo models.

### Method
POST

### Endpoint
/vertex/v1beta1/models/{model}:predictLongRunning

### Parameters
#### Path Parameters
- **model** (string) - Required - The Veo model alias (e.g., `or-veo-*`).

#### Request Body
(Raw Veo video generation request body format - details not provided in source)

### Response
#### Success Response (200)
(Details on the operation object returned - not provided in source)
```

--------------------------------

### List CLI Sessions

Source: https://www.openclacky.com/docs/session-management

Use the `-l` flag to list recent sessions for the current directory, showing names, task counts, and creation times.

```bash
openclacky -l
```

--------------------------------

### Update OpenClacky with AliYun Mirror

Source: https://www.openclacky.com/docs/faq

If the default RubyGems source is slow or times out in China, use this command with a mirror source to update OpenClacky.

```bash
gem update openclacky --source https://mirrors.aliyun.com/rubygems/

```

--------------------------------

### Register Custom Channel Adapter

Source: https://www.openclacky.com/docs/extend-channel-adapter

This line is essential for registering your custom adapter with the Clacky system. Do not remove it.

```ruby
Clacky::Channel::Adapters.register(:slack, SlackAdapter)

```

--------------------------------

### Define Extension Configuration in ext.yml

Source: https://www.openclacky.com/docs/extend-api

Specify extension metadata, configuration options, and API contributions within the ext.yml file.

```yaml
id: gh-webhook
name: GitHub Webhook
version: "0.1.0"
public: true             # top-level opt-in for public endpoints (see below)
config:                  # arbitrary config, read via config["key"] in the handler
  webhook_secret: ...
contributes:
  api: api/handler.rb

```