All Products
Search

This Product

    PolarDB:Configure a PolarDB Agent Express application

    Document Center

    PolarDB:Configure a PolarDB Agent Express application

    Last Updated:Jun 24, 2026

    By default, a new PolarDB Agent Express application cannot be accessed from the public internet, nor can it access external networks. This can cause issues such as connection failures or an inability to call external APIs when you develop and run the PolarDB Agent Express application. This topic explains the basic configurations for a PolarDB Agent Express application, including security settings, getting connection endpoints and application parameters, and enabling public network access. These steps help you use your PolarDB Agent Express application securely and efficiently.

    Security settings

    To ensure application security, a newly created PolarDB Agent Express application denies access from all external IP addresses by default. You must configure an IP address whitelist or an ECS security group to grant access from your development environment or application server.

    Note

    The application whitelist is separate from the cluster whitelist and must be configured independently.

    Before you begin, go to the management page for your target PolarDB Agent Express application:

    1. Log on to the PolarDB console. On the cluster details page, click AI Capabilities > AI Applications in the left-side navigation pane.

    2. On the AI Applications page, click your Application ID/Name to go to the application details page, and then configure the settings on the Whitelist tab.

    IP Whitelists

    Use an IP address whitelist when you need to access a PolarDB Agent Express application from a fixed public IP address, such as a local development machine or an office egress IP, or from specific IP addresses within a VPC.

    • If an ECS instance needs to access the application, find the IP address of the ECS instance on its Instance Details page and add the IP address to the IP address whitelist.

      • If your ECS instance and the application are in the same VPC, add the private IP address of the ECS instance or the CIDR block of its VPC.

      • If your ECS instance and the application are not in the same VPC, add the public IP address of the ECS instance, or add the instance's security group.

    • If your local server, computer, or another cloud server needs to access the application, add its public IP address to the IP address whitelist.

    Configuration procedure

    Click Add Whitelist or Configure an existing IP whitelist group. The rules are as follows:

    • Group name: The name must be 2 to 120 characters long and contain only lowercase letters, digits, and underscores (_). It must start with a letter and end with a letter or a digit.

    • IP format: Supports single IP addresses, such as 192.168.0.1, and CIDR blocks, such as 192.168.0.0/24. Separate multiple IP addresses or CIDR blocks with a comma (,), for example, 192.168.0.1,192.168.0.0/24.

    • Default rule: The application includes a group named default with an IP address of 127.0.0.1. This setting effectively blocks all external access.

    • High-risk setting: Setting the IP address to 0.0.0.0/0 allows access from any IP address. This poses a security risk and should only be used with caution for testing or in specific scenarios.

    Security Groups

    When you need to authorize all ECS instances within the same security group (especially for auto scaling groups where IP addresses can change dynamically) to access the PolarDB Agent Express application, we recommend that you use an ECS security group to facilitate centralized management and dynamic authorization.

    Note

    • For more information about ECS security groups and how to configure them, see ECS Security Groups.

    • You can also configure the IP addresses of your ECS instances in the IP Whitelists. ECS instances in either the IP list or the security group can access the PolarDB Agent Express application.

    Configuration procedure

    Click Select Security Groups to associate the required ECS security group with the PolarDB Agent Express application.

    Get application connection endpoints

    A PolarDB Agent Express application provides a VPC private endpoint by default to ensure secure and efficient communication between cloud resources. If you need to debug code in your local development environment or connect to the PolarDB Agent Express application using external tools, you can request a public endpoint.

    Procedure

    1. Log on to the PolarDB console. On the cluster details page, click AI Capabilities > AI Applications in the left-side navigation pane.

    2. On the AI Applications page, click your Application ID/Name to go to the application details page. On the Basic Information tab, find the Topology section and view the Public network address or Private network address under Application Link.

    Note

    • You must request the Public network address by clicking Application.

    • The Public network address provides only an IP address and port, not a domain name. If you need a domain name, you can bind a custom one.

    Connection endpoint description

    • openclaw: The Openclaw Dashboard endpoint.

    • ssh: The SSH endpoint.

    Get application configuration

    You can view and modify configuration settings for a PolarDB Agent Express application, including the OpenClaw gateway authentication token, SSH logon password, and model configurations, on the Configure tab.

    Configuration procedure

    1. Log on to the PolarDB console. On the cluster details page, click AI Capabilities > AI Applications in the left-side navigation pane.

    2. On the AI Applications page, click your Application ID/Name to go to the application details page. Then, configure the settings on the Configure tab.

    3. (Optional) To modify a parameter value, click Modify in the upper-left corner.

    Note

    Modifying some parameters automatically restarts the PolarDB Agent Express application. We recommend performing this operation during off-peak hours.

    The parameter table on the Configurations tab includes the following cluster parameters: Model (including the Model Studio model name, such as qwen3.5-plus, the API key, and the base URL https://dashscope.aliyuncs.com/compatible-mode/v1), secret.ssh.password (SSH password), and secret.gateway.auth.token (gateway authentication token). Modifying any of these parameters requires an application restart. The system validates the format of the password and token parameters by using regular expressions.

    Parameter descriptions

    Parameter

    Description

    Model

    Model-related configurations.

    secret.ssh.password

    The SSH logon password.

    Important

    • Password format: Must be at least 16 characters long and contain at least one uppercase letter, one lowercase letter, and one digit.

    • The PolarDB Agent Express application does not store or display your SSH logon password in plaintext. Before your first logon, you must reset the password. The password cannot be recovered. If forgotten, it must be reset.

    secret.gateway.auth.token

    The OpenClaw gateway authentication token.

    Enable public network access

    By default, a PolarDB Agent Express application cannot access external networks. To allow access, you must configure a NAT gateway in the VPC that contains the application's cluster.

    Configuration procedure

    1. Create an Internet NAT Gateway: Go to the NAT Gateway - Internet NAT Gateway buy page to create one. During creation, ensure you select the same VPC and vSwitch as your or PolarDB for PostgreSQL cluster. On the NAT gateway creation page, set the billing method to pay-as-you-go, enter an instance name such as nat-20260309, and set Region to the region of your target cluster. For VPC Network and vSwitch, select the VPC and vSwitch of your target cluster. Set Network Type to Internet NAT Gateway. In the Elastic IP Address section, select New Elastic IP Address, configure the peak bandwidth, and then click Create.

    2. Configure an SNAT entry: Go to the Internet NAT Gateway page. In the Actions column for the target gateway, click Configure SNAT , and then click Create SNAT Entry. Configure the parameters as follows:

      • SNAT Entry: VPC-level.

      • Select EIP: Select the EIP that provides public network access.

    Note

    Enabling public network access incurs charges for the Internet NAT Gateway and public network traffic. For more information, see NAT Gateway billing.

    FAQ

    Q: I have created an Internet NAT Gateway and configured an SNAT entry, but my PolarDB Agent Express application still cannot connect to the public internet. Why?

    A: This may be because the VPC routing information is missing on your Internet NAT Gateway instance. Follow these steps to investigate:

    1. Go to the Internet NAT Gateway page, find the target gateway, and click its name to open the details page. Check if the VPC routes that point to the NAT gateway section is empty.

    2. If it is empty, click Go to Configure to add a route entry with the following settings:

      • Destination CIDR Block: Enter 0.0.0.0/0.

      • Next Hop Type: Select NAT Gateway.

      • NAT Gateway: Select the NAT gateway instance that you created.