Skip to main content
This feature is experimental and may have limitations. Please report any issues you encounter on OpenHands-CLI repo.

​
Prerequisites

Before using OpenHands CLI with ACP, you must first install and configure the CLI:
  1. Install OpenHands CLI by following the CLI Mode installation instructions
  2. Configure your LLM settings using the /settings command
The ACP integration will reuse the credentials and configuration from your CLI settings.

​
What is the Agent Client Protocol (ACP)?

The Agent Client Protocol (ACP) is a standardized communication protocol that enables code editors and IDEs to interact with AI agents. ACP defines how clients (like code editors) and agents (like OpenHands) communicate through a JSON-RPC 2.0 interface. For more details about the protocol, see the ACP documentation.

​
ACP Support in OpenHands CLI

OpenHands CLI implements the Agent Client Protocol, allowing you to use OpenHands directly within your code editor. When you configure your editor to use openhands acp, it will communicate with OpenHands through the standardized ACP interface. OpenHands CLI currently supports the following ACP features: ✅ Implemented:
  • Initialization - version negotiation and capability exchange
  • Session Setup - creating new sessions and loading existing ones
  • Content - including embedded content and resources
  • Prompt Turns - sending prompts and receiving responses with permission support
  • Tool Calls - executing tools and returning results
  • Agent Plan - sharing agent’s planned actions
  • Confirmation Mode - user authorization for tool calls and prompt turns
  • Slash Commands - for changing confirmation mode during a session
Feel free to open issues on the OpenHands-CLI repo if you have feature requests or encounter any problems.

​
Confirmation Modes

OpenHands ACP supports three confirmation modes to control how agent actions are approved:

​
Always Ask (Default)

The agent will request user confirmation before executing each tool call or prompt turn. This provides maximum control and safety. 
openhands acp  # defaults to always-ask mode

​
Always Approve

The agent will automatically approve all actions without asking for confirmation. Use this mode when you trust the agent to make decisions autonomously. 
openhands acp --always-approve

​
LLM-Based Approval

The agent uses an LLM-based security analyzer to evaluate each action. Only actions predicted to be high-risk will require user confirmation, while low-risk actions are automatically approved. 
openhands acp --llm-approve

​
Changing Modes During a Session

You can change the confirmation mode during an active session using slash commands:
  • /confirm always-ask - Switch to always-ask mode
  • /confirm always-approve - Switch to always-approve mode
  • /confirm llm-approve - Switch to LLM-based approval mode
  • /help - Show all available slash commands
The confirmation mode setting persists for the duration of the session but will reset to the default (or command-line specified mode) when you start a new session.

​
ACP Integration

​
Zed IDE

Zed is a high-performance code editor with built-in support for the Agent Client Protocol. To configure OpenHands CLI with Zed:
  1. Ensure OpenHands CLI is installed and configured (see Prerequisites)
  2. Open your Zed editor, use Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) to open the command palette, and search for agent: open settings
Zed Command Palette
  1. Then on the right side, click on + Add Agent and select Add Custom Agent
Zed Add Custom Agent
  1. Add the following to the "agent_servers" field:
{
  "agent_servers": {
    "OpenHands": {
      "command": "uvx",
      "args": [
        "openhands",
        "acp"
      ],
      "env": {}
    }
  }
}
To use a different confirmation mode by default, add the mode flag to the args array:
{
  "agent_servers": {
    "OpenHands": {
      "command": "uvx",
      "args": [
        "openhands",
        "acp",
        "--always-approve"
      ],
      "env": {}
    }
  }
}
Replace --always-approve with --llm-approve for LLM-based approval, or omit the flag to use the default always-ask mode.
  1. Save the file
  2. You can now use OpenHands within Zed!
Zed Use OpenHands Agent

​
Troubleshooting

If you encounter issues while using OpenHands in Zed with the ACP plugin, you can access detailed debug logs:
  1. Open the command palette with Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
  2. Type and select acp debug log to view detailed debug information
  3. Review the logs for any errors or warnings
  4. Restart a new conversation to reload connections after making configuration changes
The debug logs can help you identify configuration issues, connection problems, or errors in your setup.
If you encounter persistent issues, verify that OpenHands CLI is properly configured (see Prerequisites) and that all server commands are executable from your system PATH.

​
See Also