Update FAQ with Claude.ai connection troubleshooting - #2066
Conversation
Added troubleshooting information for Claude.ai connection issues related to wildcard certificates.
|
@codex review — apply the review criteria in .gemini/styleguide.md in addition to AGENTS.md guidance |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c606883cd9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| If your Home Assistant (or reverse proxy) is served over HTTPS with a | ||
| **wildcard certificate** (`*.example.com`), Claude may fail to connect even | ||
| though the same URL loads fine in a browser and works with `curl`. |
There was a problem hiding this comment.
When the certificate is publicly trusted, has a complete chain, and its wildcard matches the connector hostname, standard TLS verification accepts it; wildcard issuance by itself does not explain a Claude connection failure. This section therefore sends affected users to reissue a certificate even though the likely causes are an incomplete chain, hostname mismatch, or proxy/network filtering, and the new certificate will only appear to help if it incidentally changes one of those conditions. Please document the specific certificate/chain condition that Claude rejects, or remove the wildcard-specific diagnosis.
Useful? React with 👍 / 👎.
|
|
||
| **Check for a port in the URL.** Your connector URL is built on your Home Assistant's own public address, which must **not** contain a port such as `:8123` (or any other port). To check, open just that base address (e.g. `https://ha.example.com`, without the `/api/webhook/...` secret path) in a browser — it should bring up your HA login page. Remote clients cannot reach a URL that carries a port, even though it loads fine in your own browser. Home Assistant can still listen on 8123 internally, as long as a reverse proxy, tunnel, or 443 port-forward serves that hostname — just don't put the port in the URL you paste. | ||
|
|
||
| ### Claude can't connect to hosts using a wildcard certificate |
There was a problem hiding this comment.
The public FAQ linked from README.md and the setup guides is independently implemented in site/src/pages/faq.astro; it does not consume docs/FAQ.md, and its existing claude-ai-connection section remains unchanged. As a result, this new troubleshooting advice will be absent from the project's primary user-facing FAQ, so mirror the entry there (and add it to that page's table of contents if it remains a separate item).
AGENTS.md reference: site/AGENTS.md:L29-L35
Useful? React with 👍 / 👎.
|
Please address the codex feedback. Claude.ai can be flaky with connection so we cannot definitely blame one thing, but I think the advice doesn't hurt. Either way please update the astro site FAQ as well as codex suggested. |
3 participants
What does this PR do?
Added troubleshooting information for Claude.ai connection issues related to wildcard certificates.
Type of change
Testing
uv run pytest)uv run ruff check)Checklist