convex-logs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Check Convex logs

查看Convex日志

Use this skill when you need to inspect what is happening in a Convex deployment: failed actions, validation errors, 401 unauthorized from external APIs, or which functions ran and how long they took.

当你需要检查Convex部署中的情况时可以使用该技能：比如动作执行失败、验证错误、外部API返回401未授权，或者查看哪些函数已运行及其耗时。

When to use this skill

适用场景

User reports an error from Convex (e.g. "unauthorized", "ArgumentValidationError", action timeout).
You need to confirm which Convex deployment (dev vs prod) is being used.
You need to see recent function executions (queries, mutations, actions) and their success/failure.
You are debugging Convex env vars (e.g. OA_INTERNAL_KEY, PUBLIC_API_URL) and want to correlate with API responses in logs.

用户反馈Convex相关错误（例如“unauthorized”、“ArgumentValidationError”、动作超时）。
你需要确认正在使用的是哪个Convex部署（开发环境vs生产环境）。
你需要查看最近的函数执行记录（查询、变更、动作）及其成功/失败状态。
你正在调试Convex环境变量（例如OA_INTERNAL_KEY、PUBLIC_API_URL），并希望与日志中的API响应关联分析。

Prerequisites

前置条件

The project must use Convex and have
```
npx convex
```
(or
```
convex
```
CLI) available.
Run Convex commands from the app directory that contains the
```
convex/
```
folder (e.g.
```
apps/web
```
in a monorepo).
You must be logged in and have the correct Convex project linked (
```
npx convex dashboard
```
to verify).

项目必须使用Convex，且可使用
```
npx convex
```
（或
```
convex
```
CLI）。
从包含
```
convex/
```
文件夹的应用目录中运行Convex命令（例如 monorepo 中的
```
apps/web
```
）。
你必须已登录并关联了正确的Convex项目（可通过
```
npx convex dashboard
```
验证）。

Default deployment: dev vs prod

默认部署：开发环境vs生产环境

Important: By default,

convex logs

and

convex env

target the dev deployment. For production issues (e.g. openagents.com), you must pass

--prod

Dev (default):
```
npx convex logs
```
streams from the project's dev deployment.
Prod:
```
npx convex logs --prod
```
streams from the project's production deployment.

Same for env vars:

npx convex env list

shows dev;

npx convex env list --prod

shows production.

重要提示： 默认情况下，

convex logs

和

convex env

指向开发部署。针对生产环境问题（例如openagents.com），必须添加

--prod

参数。

开发环境（默认）：
```
npx convex logs
```
流式传输项目开发部署的日志。
生产环境：
```
npx convex logs --prod
```
流式传输项目生产部署的日志。

环境变量命令同理：

npx convex env list

显示开发环境变量；

npx convex env list --prod

显示生产环境变量。

Commands

命令

Stream or fetch logs

流式传输或获取日志

bash

undefined

bash

undefined

From the app that has convex/ (e.g. apps/web)

进入包含convex/的应用目录（例如apps/web）

cd apps/web

Stream logs (default: dev). Use Ctrl+C to stop.

流式传输日志（默认：开发环境）。按Ctrl+C停止。

npx convex logs

Stream production logs

流式传输生产环境日志

npx convex logs --prod

Show last N log entries then exit (no streaming). Good for quick checks.

显示最后N条日志条目后退出（非流式传输）。适合快速检查。

npx convex logs --prod --history 30

Include successful executions (default is failures only in some contexts)

包含成功的执行记录（某些场景下默认仅显示失败记录）

npx convex logs --prod --history 25 --success

undefined

npx convex logs --prod --history 25 --success

undefined

Log command options

日志命令选项

Option	Meaning
`--prod`	Use the production deployment (required for prod debugging).
`--history [n]`	Show the last `n` log entries; then exit instead of streaming.
`--success`	Include successful function runs in the output.
`--jsonl`	Output raw log events as JSONL.
`--deployment-name <name>`	Target a specific deployment (e.g. `dev:effervescent-anteater-82` ).
`--env-file <path>`	Use env file for CONVEX_DEPLOYMENT or similar.

选项	说明
`--prod`	使用生产部署（调试生产环境问题时必填）。
`--history [n]`	显示最后 `n` 条日志条目；然后退出而非持续流式传输。
`--success`	在输出中包含成功的函数运行记录。
`--jsonl`	以JSONL格式输出原始日志事件。
`--deployment-name <name>`	针对特定部署（例如 `dev:effervescent-anteater-82` ）。
`--env-file <path>`	使用指定的环境文件来设置CONVEX_DEPLOYMENT等变量。

Inspect environment variables

检查环境变量

Convex actions do not read

.env.local

. They only see variables set in the Convex deployment (Dashboard or CLI). To see what the deployment has:

bash

undefined

Convex动作不会读取

.env.local

文件。它们仅能访问Convex部署中设置的变量（通过控制台或CLI）。要查看部署中的变量：

bash

undefined

List env vars on dev (default)

列出开发环境的变量（默认）

npx convex env list

List env vars on production

列出生产环境的变量

npx convex env list --prod

Get a single variable (e.g. confirm OA_INTERNAL_KEY is set; value is hidden in output)

获取单个变量（例如确认OA_INTERNAL_KEY已设置；输出中会隐藏值）

npx convex env get OA_INTERNAL_KEY --prod


Use this to confirm that keys and URLs (e.g. `OA_INTERNAL_KEY`, `PUBLIC_API_URL`) are set on the deployment that's actually serving the app.

npx convex env get OA_INTERNAL_KEY --prod


使用该命令可以确认密钥和URL（例如`OA_INTERNAL_KEY`、`PUBLIC_API_URL`）是否在实际提供服务的部署中已正确设置。

Typical workflow

典型工作流

Reproduce the issue (e.g. open Hatchery, trigger an action that returns 401).

Fetch recent prod logs (if the app is production):

bash

cd apps/web
npx convex logs --prod --history 30 --success

Find the failing function in the output (e.g.

[CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] ... 401 'unauthorized'

Confirm which deployment is used: logs show the deployment name (e.g.
```
successful-mongoose-647
```
for prod).
Check env vars for that deployment:
```
npx convex env list --prod
```
(or without
```
--prod
```
for dev).
Fix env in Convex (Dashboard or
```
npx convex env set ...
```
) or fix the calling code; redeploy if needed.

复现问题（例如打开Hatchery，触发返回401的动作）。
获取最近的生产环境日志（如果应用是生产环境）：
bash
```
cd apps/web
npx convex logs --prod --history 30 --success
```

在输出中找到失败的函数（例如

[CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] ... 401 'unauthorized'

）。

确认使用的部署：日志中会显示部署名称（例如生产环境的
```
successful-mongoose-647
```
）。
检查该部署的环境变量：
```
npx convex env list --prod
```
（开发环境则去掉
```
--prod
```
）。
修复问题：在Convex中设置正确的环境变量（通过控制台或
```
npx convex env set ...
```
），或者修复调用代码；必要时重新部署。

Example log output

日志输出示例

Watching logs for production deployment successful-mongoose-647...
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getInstance)] Function executed in 434 ms
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] '[openclawApi getRuntimeStatus] API error response:' 401 'unauthorized'
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] Uncaught Error: unauthorized ...

Here,

getInstance

succeeded but

getRuntimeStatus

got 401 from the external API—often a mismatch of

OA_INTERNAL_KEY

between Convex and the API worker.

Watching logs for production deployment successful-mongoose-647...
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getInstance)] Function executed in 434 ms
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] [ERROR] '[openclawApi getRuntimeStatus] API error response:' 401 'unauthorized'
2/4/2026, 12:39:06 PM [CONVEX A(openclawApi:getRuntimeStatus)] Uncaught Error: unauthorized ...

在此示例中，

getInstance

执行成功，但

getRuntimeStatus

从外部API收到401未授权错误——通常是由于Convex和API服务端的

OA_INTERNAL_KEY

不匹配导致的。

Troubleshooting

故障排除

"No logs" or wrong deployment: Use
```
--prod
```
when the live app uses the production Convex deployment.
401 from Convex actions calling an API: Set
```
OA_INTERNAL_KEY
```
(and
```
PUBLIC_API_URL
```
if needed) in the same Convex deployment that runs the action (
```
npx convex env set OA_INTERNAL_KEY "..." --prod
```
), and ensure the API worker has the same key (e.g.
```
npx wrangler secret put OA_INTERNAL_KEY
```
in the API app).
Timeout when streaming: Use
```
--history N
```
to fetch a finite number of entries and exit instead of streaming.
Need a specific deployment: Use
```
--deployment-name <name>
```
(e.g.
```
dev:effervescent-anteater-82
```
) for that deployment's logs.

“无日志”或部署错误： 当线上应用使用Convex生产部署时，需添加
```
--prod
```
参数。
Convex动作调用API时返回401： 在运行该动作的Convex部署中设置
```
OA_INTERNAL_KEY
```
（必要时同时设置
```
PUBLIC_API_URL
```
）（
```
npx convex env set OA_INTERNAL_KEY "..." --prod
```
），并确保API服务端使用相同的密钥（例如在API应用中执行
```
npx wrangler secret put OA_INTERNAL_KEY
```
）。
流式传输时超时： 使用
```
--history N
```
参数获取指定数量的日志条目后退出，而非持续流式传输。
需要针对特定部署： 使用
```
--deployment-name <name>
```
参数（例如
```
dev:effervescent-anteater-82
```
）查看该部署的日志。