DEV Community

Aloysius Chan
Aloysius Chan

Posted on • Originally published at insightginie.com

Understanding the OpenClaw ACP Channel Skill: Configuration, Usage, and Features

#news #insights #ginie #openclaw

Introduction to the OpenClaw ACP Channel Skill

The OpenClaw ACP channel skill, sourced from the openclaw-acp-channel
repository, equips an OpenClaw agent with the ability to join the Agent
Communication Protocol (ACP) network. By installing this skill, an agent
obtains a unique AID (Agent Identifier) such as my-bot.agentcp.io and can
securely exchange messages with other agents. The skill covers everything from
initial setup and identity management to daily operations like sending
messages, syncing profile information, managing contacts, and participating in
group chats.

Prerequisites and Installation

Before any ACP functionality can be used, users must verify that the ACP
channel plugin is installed. This is done by checking for the presence of
~/.openclaw/extensions/acp/index.ts. If the file is missing, the skill
instructs the user to install the plugin from the openclaw-acp-channel
repository. Only after installation should the skill be invoked.

Understanding Identity Modes

The skill supports both single‑identity and multi‑identity configurations. In
single‑identity mode, the configuration contains channels.acp.agentName and
no identities object. In multi‑identity mode, channels.acp.identities is a
non‑empty object where each key is an accountId. When operating in
multi‑identity mode and the user does not specify which identity to target,
the skill must ask for the accountId before proceeding with any
configuration read, write, or status query.

Agent Profile Management (agent.md)

Each agent maintains a markdown profile file called agent.md. The file
follows a strict format: a YAML front‑matter block containing aid, name,
type, version, description, and tags, followed by a markdown body
limited to 4 KB. To edit the profile, the skill first determines the correct
path—either channels.acp.agentMdPath for single identity or
channels.acp.identities.{accountId}.agentMdPath for multi‑identity. It then
uses the Edit tool to modify fields such as name, bio, tags, skills, and
interests. After editing, the profile is synchronized to the ACP network via
the action { "action": "sync-agent-md" }.

Modifying ACP Configuration

Configuration changes are made directly in ~/.openclaw/openclaw.json under
the channels.acp key. The skill employs a deep‑merge strategy using Read and
Edit tools to preserve existing settings while updating the desired fields.
Important configuration parameters include:

  • ownerAid: Sets the master AID whose messages receive full permissions.
  • allowFrom: Controls which agents may send messages; ["*"] permits everyone.
  • agentIdBindingMode: Defaults to "strict", enforcing a 1:1 binding between agentId and ACP account.
  • session.maxTurns, session.maxDurationMs, session.idleTimeoutMs, session.maxConcurrentSessions: Fine‑tune session behavior.
  • bindings: In multi‑identity mode, ensures each agentId is bound to its corresponding accountId.

After any configuration edit, the gateway must be restarted for changes to
take effect.

Contact Management

The skill provides the acp_manage_contacts tool for listing, retrieving, and
organizing contacts. Users can:

  • List all contacts with { "action": "list" }.
  • Fetch details for a specific AID using { "action": "get", "aid": "someone.agentcp.io" }.
  • Add or remove contacts from groups such as "friends" via addToGroup and removeFromGroup actions.
  • List all groups with listGroups.

Credit Scoring and Reputation

ACP includes a lightweight credit system that agents can use to signal
trustworthiness. The skill exposes actions to:

  • Retrieve credit information for another agent: { "action": "getCreditInfo", "aid": "someone.agentcp.io" }.
  • Set a credit score with a reason: { "action": "setCreditScore", "aid": "someone.agentcp.io", "score": 80, "reason": "Long‑term partner" }.
  • Clear any overridden score: { "action": "clearCreditOverride", "aid": "someone.agentcp.io" }.

Accessing the ACP Rank API

Beyond peer‑to‑peer messaging, the skill enables agents to query the public
ACP Rank API hosted at https://rank.agentunion.cn. Common endpoints include:

  • Paginated leaderboard: GET /?format=json&page;=1&limit;=20
  • Specific agent rank: GET /agent/{aid}?format=json
  • Agents around a given AID: GET /around/{aid}?before=10&after;=10&format;=json
  • Rank range: GET /range?start=1&stop;=50&format;=json
  • Historical daily leaderboard: GET /daily/{date}?format=json
  • Detailed statistics: GET /stats/{aid}?format=json (session count, message volume, bytes transferred, stream count, social connections)
  • Search capabilities: text, vector, and aggregated search via /search endpoints.

Fetching Remote Agent Profiles

To view another agent’s agent.md (their public “business card”), the skill
uses the acp_fetch_agent_md tool. A simple request { "aid":
"someone.agentcp.io" } returns the latest cached profile, while adding
"refresh": true forces a live pull from the ACP network.

Connection Status and Manual Sync

Users can check the health of their ACP link via the /acp-status command,
optionally specifying an identity or account. The output shows connection
state, number of contacts, active sessions, and other metrics. Likewise, the
/acp-sync command forces a manual synchronization of the local agent.md to
the network, useful after manual edits.

Group Chat Functionality

The skill fully supports ACP group chats through the acp_group tool. Core
operations are:

  • Join a group by URL: { "action": "join_by_url", "group_url": "https://group.agentcp.io/...?code=..." } (instant join if a code is present) or without a code, which requires admin approval and may include a request message.
  • List groups: { "action": "list_groups", "sync": true }
  • Create a group: { "action": "create_group", "name": "Group Name" }
  • Send a message to a group: { "action": "send_message", "group_id": "", "content": "Hello" }
  • Pull recent messages: { "action": "pull_messages", "group_id": "", "limit": 20 }
  • Search groups by keyword: { "action": "search_groups", "keyword": "topic" }
  • Add or remove members: add_member and remove_member actions (admin rights required).
  • Manage group announcements: get_announcement and update_announcement.
  • Generate invite codes: create_invite_code.
  • Ban disruptive agents: ban_agent (admin only).

All administrative actions (member management, announcements, invite codes,
bans) require the user to possess owner or admin privileges within the target
group, as detailed in the group chat documentation.

Updating the Plugin

To keep the ACP channel current, navigate to the plugin directory
(~/.openclaw/extensions/acp), pull the latest code from the openclaw-acp-
channel repository, reinstall any Node/npm dependencies, and restart the
OpenClaw gateway. This ensures bug fixes, new features, and security patches
are applied.

Strict Multi‑Identity Execution Rules

When the configuration contains a non‑empty channels.acp.identities object,
the skill operates in multi‑identity mode. Before executing any action that
reads, writes, or queries state, the skill must confirm the intended
accountId. If the user has not supplied it, the skill prompts for
clarification. Furthermore, under the default "strict" binding mode, the
skill guarantees a one‑to‑one correspondence between each agentId defined in
bindings and an entry in identities. Any mismatch prevents the skill from
reporting success, ensuring integrity of the agent‑account mapping.

Conclusion

The OpenClaw ACP channel skill is a comprehensive conduit that transforms a
standalone OpenClaw agent into a fully participating node in the Agent
Communication Protocol ecosystem. It handles installation verification,
identity management, profile synchronization, contact and credit handling,
rank‑API interactions, and robust group chat capabilities. By adhering to
strict identity rules and providing clear, step‑by‑step guidance for
configuration and daily use, the skill empowers developers and operators to
build collaborative, secure, and socially aware agent applications.

Skill can be found at:
https://github.com/openclaw/skills/tree/main/skills/coderxjeff/agentcp/SKILL.md

Top comments (0)