Automatic OWL Installation¶

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

OWL Skill is a supporting capability for AI tools. It helps AI tools recognize the local owl command, understand the OWL tool directory, and more stably invoke diagnostic capabilities such as logs, metrics, events, and traces. The automatic installation will install OWL Skill together with OWL CLI.

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

If the current environment cannot execute terminal commands, cannot access the external network or the OWL CLI Endpoint in the corporate network, or requires offline installation, please use Manual OWL Installation.

Use Cases¶

Applicable to the following scenarios:

• AI tools have the permission to execute terminal commands
• The current environment can access the OWL CLI Endpoint and installation resource addresses
• The current environment allows writing OWL configurations in the local user directory
• Users can provide the OWL CLI Endpoint and temporary authorization code corresponding to the workspace

Not applicable to the following scenarios:

• The current tool is a pure chat tool that cannot execute terminal commands
• The current environment is a restricted network or offline environment
• The current environment does not allow AI tools to write local configurations
• Each command in the installation process requires manual review before execution

Installation Command¶

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 the workspace
• Replace <YOUR_TEMP_CODE> with the temporary authorization code generated in the TrueWatch console

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

Installation parameters:
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). You can choose according to the language environment of the AI tool.

Parameter Description¶

OWL_REGISTRY_ENDPOINT only needs to fill in the root address of the Endpoint. Do not manually append /api/v1 or other paths.

Path to obtain the 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¶

OWL CLI services provide independent Endpoints by site. Please select the corresponding service address based on the node where the workspace is located.

Execution Content¶

The AI tool will automatically perform the following operations based on the installation instructions:

1. Download and install OWL CLI
2. Write the OWL CLI Endpoint corresponding to the workspace
3. Use OWL_TEMP_CODE to exchange for an API Key
4. Write the authentication information into the local OWL configuration
5. Execute owl sync to synchronize the tool directory
6. Install OWL Skill
7. Verify the availability of the owl command

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

Security Instructions¶

Automatic installation does not require providing the API Key plaintext to the AI tool. The AI tool will use OWL_TEMP_CODE to exchange for an API Key and write the authentication information into the local OWL configuration. During the installation process, the API Key plaintext must not be displayed in replies, logs, or command outputs.

OWL_TEMP_CODE is a short-term valid temporary authorization credential, only used for exchanging for an API Key during the installation phase. This credential cannot directly call APIs, but it should still be treated as sensitive information within its validity period. Do not paste it publicly, write it into long-term logs, submit it to code repositories, or share it in documents.

After automatic installation is complete, the resources accessible and operations executable by OWL are still determined by the exchanged API Key and follow the permission configurations in the TrueWatch workspace.

Common Troubleshooting¶

AI Tool Cannot Execute Commands¶

If the AI tool prompts that it cannot execute terminal commands, re-execute the installation command in an AI tool that has terminal execution permissions, or switch to Manual OWL Installation.

Temporary Authorization Code Invalid, Expired, or Unauthorized¶

If prompted that the authorization code is invalid, expired, or unauthorized, regenerate OWL_TEMP_CODE in the TrueWatch console and then re-execute the installation command.

Endpoint Unreachable¶

If prompted that the Endpoint is unreachable, confirm the following:

• The current environment can access the external network or the OWL CLI Endpoint in the corporate network
• The node where the workspace is located matches OWL_REGISTRY_ENDPOINT
• OWL_REGISTRY_ENDPOINT does not have /api/v1 or other paths appended

owl Command Not Recognized After Installation¶

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

You can check by executing the following commands:

owl --help
owl config show

Tool Directory Synchronization Failed¶

If owl sync returns an authentication, permission, or network error, confirm:

• Whether OWL_TEMP_CODE has been successfully exchanged for an 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, please refer to Troubleshooting.