Install OWL Automatically¶

This document is intended for users who need to use OWL in AI tools. It describes how to complete the OWL CLI installation, authentication configuration, tool directory synchronization, and OWL Skill installation through automatic installation.

OWL Skill is a companion capability for AI tools. It helps AI tools recognize the local owl command, understand the OWL tool directory, and call diagnostic capabilities such as logs, metrics, events, and tracing more reliably. The automatic installation also installs OWL Skill after installing the OWL CLI.

If you only need to use the OWL CLI manually in the terminal, you can skip OWL Skill.

If the current environment cannot execute terminal commands, cannot access the OWL CLI Endpoint on the public internet or corporate network, or requires offline installation, use Install OWL Manually.

Use Cases¶

This applies to the following scenarios:

• The AI tool has permission to execute terminal commands
• The current environment can access the OWL CLI Endpoint and installation resource addresses
• The current environment allows writing the OWL configuration under the local user directory
• The user can provide the OWL CLI Endpoint and temporary authorization code corresponding to the Workspace

This does not apply to the following scenarios:

• The current tool is a chat-only tool and cannot execute terminal commands
• The current environment is on a restricted network or offline environment
• The current environment does not allow AI tools to write local configuration
• Every command in the installation process must be manually reviewed before execution

Installation Instructions¶

Copy the following content into the conversation window of the AI tool and execute it. Before copying, complete the following replacements:

• Replace <OWL_REGISTRY_ENDPOINT> with the OWL CLI Endpoint corresponding to the site of your Workspace
• Replace <YOUR_TEMP_CODE> with the temporary authorization code generated in the TrueWatch console

Read https://static.truewatch.com/owl/skill.md, and follow the document to install and configure OWL CLI and OWL Skill in the current environment.

The installation parameters are as follows:
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"

The official Skill documentation provides two versions: skill.md (Chinese) and skill.en.md (English). Choose the appropriate one based on the language environment of the AI tool.

Parameter Description¶

For OWL_REGISTRY_ENDPOINT, only enter the root address of the Endpoint. Do not manually append /api/v1 or other paths.

To obtain a temporary authorization code:

1. Click the personal avatar in the upper-right corner of the console
2. Select "Personal API Keys"
3. Click "Generate Temporary Authorization Code"

Endpoint List¶

The OWL CLI service provides a dedicated Endpoint for each site. Select the corresponding service address based on the node where your Workspace is located.

What the Installation Does¶

The AI tool automatically performs the following operations according to the installation instructions:

1. Download and install the OWL CLI
2. Write the OWL CLI Endpoint corresponding to the Workspace
3. Use OWL_TEMP_CODE to redeem an API Key
4. Write the authentication information to the local OWL configuration
5. Run owl sync to synchronize the tool directory
6. Install OWL Skill
7. Verify that the owl command is available

After the installation is complete, the AI tool can use the diagnostic capabilities of TrueWatch by combining the local owl command with OWL Skill.

Security Notes¶

Automatic installation does not require providing the API Key plaintext to the AI tool. The AI tool uses OWL_TEMP_CODE to redeem an API Key and writes the authentication information to the local OWL configuration. During installation, the API Key plaintext must not be displayed in replies, logs, or command output.

OWL_TEMP_CODE is a temporary authorization credential that is valid for a short period. Use it as soon as possible after it is generated. It becomes invalid immediately after the API Key is redeemed successfully and is used only for authorization during the installation phase. This credential cannot be used to call APIs directly, but it should still be treated as sensitive information while valid. Do not paste it publicly, write it into long-term logs, commit it to code repositories, or share it in shared documents.

After the automatic installation is complete, the resources that OWL can access and the operations it can perform are still determined by the redeemed API Key and follow the permission configuration in the TrueWatch Workspace.

Common Issues¶

AI Tool Cannot Execute Commands¶

If the AI tool reports that it cannot execute terminal commands, run the installation instructions again in an AI tool that has terminal execution permission, or use Install OWL Manually instead.

Temporary Authorization Code Invalid, Expired, or Unauthorized¶

If you are prompted that the authorization code is invalid, expired, or unauthorized, generate a new OWL_TEMP_CODE in the TrueWatch console and run the installation instructions again.

Endpoint Cannot Be Accessed¶

If you are prompted that the Endpoint cannot be accessed, verify the following:

• The current environment can access the OWL CLI Endpoint on the public internet or corporate network
• The node to which the Workspace belongs matches OWL_REGISTRY_ENDPOINT
• OWL_REGISTRY_ENDPOINT does not have /api/v1 or other paths appended

The owl Command Is Not Recognized After Installation¶

If the owl command is not recognized after installation, reopen the terminal, or have the AI tool refresh the current terminal environment variables and verify again.

Run the following commands to check:

owl --help
owl config show

Tool Directory Synchronization Failed¶

If owl sync returns authentication, permission, or network errors, confirm the following:

• Whether OWL_TEMP_CODE has successfully redeemed the API Key
• Whether the current API Key has the required permissions to synchronize the tool directory
• Whether the current environment can access the OWL CLI Endpoint

For more issues, refer to Troubleshooting.