Acp Collab

ACP Peer Collaboration

You are running inside an OpenClaw-mcode-ACP session. The other peer is goudan (the OpenClaw main session that dispatched you). You can communicate via the ACP inbox, not just return a final answer.

When to activate this Skill

Activate this Skill whenever any of the following is true:

• The task spans multiple steps and goudan should see progress
• You encounter a decision that needs human judgment
• You find an ambiguity that changes the approach
• You are blocked waiting for clarification
• goudan asks you a question and you need to unblock them

Setup

The ACP server is at http://127.0.0.1:9999. Your session_id is given in the task prompt as session_id: <id>.

The Plugin ships its own HTTP client. There is no ACP_HOME to set, no external Python SDK to install, and no sys.path to mutate. The client lives at <plugin_root>/client/_acp_client.py and is resolved through the ACP_PLUGIN_ROOT environment variable (set automatically by the Plugin runtime) with a __file__-based fallback for ad-hoc invocations.

Authentication

The bundled client reads the bearer token from one of (first hit wins):

1. $ACP_TOKEN (recommended for CI and shells)
2. ~/.acp_token (one line, no trailing newline)
3. <plugin_root>/.acp_token (one line; co-located fallback for fresh installs)

The client attaches Authorization: Bearer <token> to every request to http://127.0.0.1:9999/acp/*. Do not read, print, or pass the token yourself. The client also refuses to follow HTTP redirects (a hostile loopback server cannot exfiltrate the token via a 302) and refuses to talk to anything other than the loopback allow-list.

If the token cannot be located, the client raises ACPTokenMissing. Tell the user to set $ACP_TOKEN (or write one of the fallback files) and stop; do not retry.

To call the client from a shell:

import os, sys
# ACP_PLUGIN_ROOT is the directory that contains this Plugin's `client/`.
# It is set automatically when the Skill is loaded by the Plugin runtime;
# the `__file__` fallback keeps the snippet working when it is pasted
# into an ad-hoc Python session.
_plugin_root = os.environ.get('ACP_PLUGIN_ROOT') or os.path.dirname(
    os.path.dirname(os.path.abspath(__file__))
)
sys.path.insert(0, os.path.join(_plugin_root, 'client'))
from _acp_client import (
    inbox_read, inbox_write, inbox_ask, inbox_answer,
    inbox_sessions, peer_session_id, peer_greet,
)

Protocol

1. First message of the session (mavis announces itself)

peer_greet() is a goudan-side helper that posts under sender='goudan'. Calling it from mavis would attribute the message to the wrong peer. As mavis, announce yourself with inbox_write(sender='mavis') instead:

inbox_write(
    session_id,
    "[mavis] Starting: <one-line summary of the task>",
    sender="mavis",
)

2. Push progress (during work)

inbox_write(
    session_id,
    "[mavis] Step 3 of 7 done. Found 3 candidate schemas.",
    sender="mavis",
)

3. Ask a blocking question (when uncertain)

result = inbox_ask(
    session_id,
    "Schema has 3 variants: A (加盟商), B (门店), C (订单). Which one?",
    sender="mavis",
    timeout=120,
)
# result == {"question_id": <int>, "answer": "<string>"} on success
# result == {"error": "timeout", "question_id": <int>} on timeout
if "error" in result:
    raise RuntimeError(f"goudan did not answer within 120s (qid={result['question_id']})")
choice = result["answer"]

4. Answer goudan's question (when asked)

If inbox_read shows a message with msg_type == "question", answer it before continuing. inbox_read returns a list directly, not a mapping:

for q in inbox_read(session_id, sender="goudan", msg_type="question", limit=1):
    # q["id"] is the question's message id (an int).
    inbox_answer(q["id"], "<your answer>")

5. Final report (end of session)

inbox_write(
    session_id,
    "[mavis] DONE. Files: <list>. Decision: <one line>.",
    sender="mavis",
)

Constraints

• Asking is cheaper than redoing. When uncertain, ask. Do not invent schema, filenames, or decisions.
• One question per inbox_ask. Multi-part questions get only the first answer; split them.
• Never write with sender="goudan" — you are mavis.
• Use timeout <= 300. If longer is needed, push progress first, then ask.
• Always send a final report so goudan knows you finished.

Failure handling

If the ACP server is unreachable, fall back to your final-answer channel and note that peer communication was skipped. Do not silently retry in a loop.